Skip to main content

统一编码规范

编码规范的目标是让不同人写出的代码看起来像同一个人写的，降低协作成本。

一、参考规范​

公司/团队可以从这些公开规范中选一个作为基础，再按需定制：

规范不是越多越好，团队能落地才是关键。

二、辅助工具全景​

工具职责替代品
ESLint代码质量检查（语法错误、最佳实践）Biome
Prettier代码格式化（缩进、引号、分号）Biome
Stylelint样式文件检查Biome（部分支持）
EditorConfig编辑器基础配置无
Husky + lint-stagedgit 提交前自动检查simple-git-hooks
commitlintcommit message 格式校验commitlint（无替代）
commitizen交互式生成 commitcz-cli

2024+ 趋势：Biome 越来越成熟，可以部分替代 ESLint + Prettier。新项目可以试试 Biome，老项目维持现状。

三、ESLint​

针对 js/ts/react/vue 等做语法检查和错误预警。ESLint 不做格式（格式交给 Prettier）。

pnpm add eslint -D
pnpm eslint --init

.eslintrc.js 推荐配置：

module.exports = {
  root: true,
  env: { browser: true, es2021: true, node: true },
  extends: [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "plugin:@typescript-eslint/recommended",
  ],
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaFeatures: { jsx: true },
    ecmaVersion: "latest",
    sourceType: "module",
  },
  plugins: ["react", "@typescript-eslint"],
  rules: {
    "no-var-requires": 0,
  },
};

vscode 记得安装 ESLint 插件，配置项：

{
  "editor.codeActionsOnSave": { "source.fixAll.eslint": "explicit" }
}

详细文档：eslint.org

四、Prettier​

统一代码格式（缩进、引号、分号等），让团队代码风格统一。

pnpm add prettier -D

推荐使用 .prettierrc.json（更直观）：

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": false,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf"
}

vscode 插件 Prettier + 配置：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

详细文档：prettier.io

注意：Prettier 和 ESLint 的格式规则要分开。在 .eslintrc 中禁用与 Prettier 冲突的规则。

五、Stylelint​

检查 css / less / scss 样式代码。

pnpm add stylelint stylelint-config-standard -D

.stylelintrc.js：

module.exports = {
  extends: "stylelint-config-standard",
  rules: {},
};

vscode 插件 Stylelint + 配置保存时自动修复：

{
  "editor.codeActionsOnSave": { "source.fixAll.stylelint": true }
}

六、EditorConfig​

解决不同编辑器之间的基础差异（缩进、换行、文件结尾）。

# .editorconfig
root = true

[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.md]
insert_final_newline = false
trim_trailing_whitespace = false

几乎所有编辑器（vscode、webstorm、sublime）都原生支持，配置一次即可生效。

七、Commitlint​

校验 commit message 是否符合规范，防止 PR 历史里出现 "fix bug" 这种无效信息。

1. 格式​

<type>(<scope>): <subject>

<body>

<footer>

2. type 类型​

type含义
feat新功能
fix修复 bug
perf性能优化
refactor重构（不影响功能）
docs文档修改
style代码格式（不是 css）
test测试相关
build构建/依赖
ciCI 配置
chore其他
revert回滚
release发版

示例：

feat(user): 支持微信登录

接入微信 OAuth 流程，新增 wechat-login 组件

Closes #123

八、Husky + lint-staged​

Husky 操作 git 钩子；lint-staged 只检查 git 暂存区文件，不浪费性能。

1. 安装​

pnpm add husky lint-staged @commitlint/cli @commitlint/config-conventional -D

⚠️ Husky v9+ 配置有变化，以下示例用 v8 兼容写法。v9 推荐 simple-git-hooks 替代。

2. package.json 追加​

{
  "scripts": {
    "prepare": "husky"
  },
  "lint-staged": {
    "src/**/*.{js,jsx,ts,tsx}": [
      "prettier --write",
      "eslint --cache --fix"
    ],
    "src/**/*.{css,less}": [
      "stylelint --fix"
    ]
  }
}

3. commitlint 配置​

commitlint.config.js：

module.exports = {
  extends: ["@commitlint/config-conventional"],
};

4. 初始化 husky​

pnpm prepare

5. 添加钩子​

npx husky add .husky/commit-msg 'pnpm commitlint --edit "$1"'
npx husky add .husky/pre-commit 'pnpm lint-staged'

.husky/commit-msg：

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
pnpm commitlint --edit $1

.husky/pre-commit：

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
pnpm lint-staged

九、其他工具​

  • commitizen：交互式生成 commit message，git cz 代替 git commit
pnpm add -D commitizen cz-conventional-changelog
npx commitizen init cz-conventional-changelog --save-dev --save-exact

十、project.json 全局脚本​

{
  "scripts": {
    "lint": "eslint . --ext .ts,.tsx --fix",
    "lint:check": "eslint . --ext .ts,.tsx",
    "format": "prettier --write \"src/**/*.{ts,tsx,less,md}\"",
    "test": "vitest",
    "typecheck": "tsc --noEmit"
  }
}

十一、Biome 简介（2024+ 新选择）​

Biome 是基于 Rust 的一体化工具，目标是一把梭：

pnpm add -D @biomejs/biome
npx @biomejs/biome init

biome.json：

{
  "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2 },
  "linter": { "enabled": true, "rules": { "recommended": true } },
  "organizeImports": { "enabled": true }
}

优缺点：

  • ✅ 一个工具搞定 lint + format + import 排序
  • ✅ 比 ESLint + Prettier 快 10~20 倍
  • ⚠️ Vue / CSS 支持还在完善
  • ⚠️ 插件生态不如 ESLint

建议：新项目可以试试 Biome，老项目保持 ESLint + Prettier。

十二、备注​

以上工具需要在项目中手动配置。更好的方式是通过自研脚手架把配置预置进去，新项目开箱即用。