在项目协作开发中， 随着业务的扩张，开发人员的增加，项目代码自然会出现爆炸性增长，这时候代码规范成了一个不可避免的问题，除了人工 code review 之外，我们需要一些自动化规范代码的工具，让我们的开发人员能够更好的专注在代码本身。
下面简单介绍 prettier、eslint、styleint、husky、commitzen、commitlint 这几个工具实现项目代码规范，我的项目是 react + vite ，我会以本项目作为示例。
Prettier
Prettier 是一个自动代码格式化工具，它自动调整代码的风格，包括缩进、空格和引号，以确保一致的代码风格。它支持多种编程语言，易于集成到编辑器和项目中，有广泛的社区支持。 Prettier 帮助团队维持一致的风格，减少风格争议，并提高代码质量。
安装
npm install --save-dev --save-exact prettier
这里解释下 --save-exact 这个选项
它用于确保安装的包的版本是精确匹配的，在我们需要确认精确的包版本，以及希望避免不期望的升级版本时候可以使用。
这样可以确保项目中的每个人都获得完全相同的 Prettier 版本。
配置
项目根目录创建两个文件，.prettierrc 、.prettierignore
.prettierrc 配置
{
"printWidth": 80, // 用于指定代码行的最大字符数。当一行的字符数超过这个值时，Prettier 会尝试将代码拆分成多行
"trailingComma": "all", // 用于指定对象和数组字面量的最后一个元素是否包含逗号。
"tabWidth": 2, // 指定用于缩进的制表符宽度或空格数量。通常情况下，推荐使用空格作为缩进字符。
"semi": true, // 控制是否在语句末尾添加分号。
"singleQuote": true, // 用于控制是否使用单引号还是双引号来包裹字符串。
"bracketSpacing": true, // 控制对象字面量的大括号内是否添加空格。
"arrowParens": "always", // 控制是否为单一箭头函数的参数添加括号。
"jsxBracketSameLine": true, // 控制 JSX 元素的起始尖括号是否与前一个元素在同一行。
"endOfLine": "auto" // 用于指定换行符的类型。可以设置为 "auto"、"lf"（换行符）或 "crlf"（回车换行符）。
}
.prettierignore 忽略文件配置
node_modules
dist
.git
这里配置好后想试试效果可以使用命令对单个文件进行格式化操作
npx prettier --write ./src/index.jsx
ESlint
ESLint 是一个静态代码分析工具，用于检测和修复 JavaScript 代码中的问题和代码质量问题。它强调规则的可定制性，允许开发人员自定义规则和适应项目需求。ESLint 主要关注代码质量、潜在问题和编码规范。
与 Prettier 的区别在于，Prettier 专注于代码格式化，即代码的排版、缩进、引号等，以确保一致的代码风格。ESLint 负责检查代码质量、潜在错误和编码规范，但不处理排版问题。通常，开发团队会同时使用 ESLint 和 Prettier，以实现代码质量和代码格式的全面检查和修复。
安装
npm install eslint --save-dev
配置
根目录创建文件 .eslintrc.js ，我这个 vite 项目生成的时候自带了 eslint，默认配置如下
module.exports = {
root: true, // 表示此配置文件是根配置文件，ESLint 在查找配置文件时会停止搜索。这意味着它是项目中的主要配置文件。
env: { browser: true, es2020: true }, // 指定了代码执行的环境。这里配置了浏览器环境和 ECMAScript 2020 版本的支持。
extends: [ // 继承其他预定义的 ESLint 配置。这里继承了以下配置：
'eslint:recommended',
'plugin:react/recommended',
'plugin:react/jsx-runtime',
'plugin:react-hooks/recommended',
],
ignorePatterns: ['dist', '.eslintrc.cjs'], // 定需要被 ESLint 忽略的文件和目录。在这个例子中，它忽略了 `dist` 目录和 `.eslintrc.cjs` 文件。
parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
// 配置解析选项。这里指定了 ECMAScript 版本为 'latest'（即最新版本），以及代码的 `sourceType` 为 'module'（表示使用 ES6 模块系统）。
settings: { react: { version: '18.2' } },
// 包含一些配置设置，这里主要是为了指定 React 版本为 '18.2'，以便 React 相关的规则能够正确运行。
plugins: ['react-refresh'],
rules: {
'react-refresh/only-export-components': [
'warn',
{ allowConstantExport: true },
],
},
}
eslint 某些规则可能会和 Prettier 冲突，这里我们安装一个插件来关闭可能与 Prettier 冲突的规则
npm install --save-dev eslint-config-prettier
并且在 eslint 配置文件中加入
extends: [
'eslint:recommended',
'plugin:react/recommended',
'plugin:react/jsx-runtime',
'plugin:react-hooks/recommended',
'prettier',
],
husky 和 lint-staged
Husky 是一个 Git 钩子工具，它允许你在 Git 操作（如提交、推送等）发生前或发生时运行自定义脚本，以确保代码的一致性、质量和规范性。需要注意的是，如果我们在整个项目上运行 Lint 会很慢，一般我们只检查更改过的文件，此时要用到 lint-staged。 安装以及使用如下：
安装
npm install --save-dev husky lint-staged
配置
目前 husky 版本 8.0.3 需要编辑 package.json 并再次运行安装命令生成 husky 配置文件
编辑 package.json > prepare 脚本并运行一次
npm pkg set scripts.prepare="husky install"
npm run prepare
并添加 hook 配置
npx husky add .husky/pre-commit "npm run pre-commit"
在 package.json 中添加以下配置:
// package.json
{
"scripts": {
"pre-commit": "lint-staged"
}
}
"lint-staged": {
"src/**/*.{js,jsx}": [
"eslint --fix",
"prettier --write",
// "git add" lint-staged 在10以上版本无需增加 git add
]
},
现在，每当提交代码的时候，Git 钩子会自动运行 ESLint、Prettier 来规范代码。
Stylelint
经过上面几个工具的安装配置，我们基本的代码规范框架已经搭建起来了，现在就是根据具体业务情况再添加不同的规范工具或者自定义配置，现在我还需要把 css 代码也做一个自动规范操作。
stylelint，一个强大的CSS过滤器，可以帮助您避免错误并强制执行约定。
安装
npm install --save-dev stylelint stylelint-config-standard
这里我项目用的是 less , 还需要额外安装 stylelint-less、postcss-less
npm install --save-dev stylelint-less postcss-less
配置
使用 stylelint 生成配置文件
npm init stylelint
直接在根目录生成了 .stylelintrc.json 配置文件，stylelint-config-standard
这个配置是 stylelint 的一些标准配置，具体内容不细述，可以查看 样式lint-config-standard - npm (npmjs.com)
然后我们再加上 stylelint-less 相关插件配置以及一些自定义规则，结果如下
{
"extends": ["stylelint-config-standard"],
"plugins": ["stylelint-less"],
"rules": {
"at-rule-no-unknown": null,
"color-no-invalid-hex": true,
"less/color-no-invalid-hex": true,
"selector-class-pattern": null,
"selector-pseudo-class-no-unknown": [
true,
{
"ignorePseudoClasses": ["global"]
}
]
},
"overrides": [
{
"files": ["**/*.less"],
"customSyntax": "postcss-less"
}
]
}
然后我们再调整下 lint-staged 配置，在提交代码前进行样式代码规范自动检查和修复
"lint-staged": {
"src/**/*.{js,jsx,less}": [
"eslint --fix",
"stylelint --fix",
"prettier --write",
]
},
这里还要修改下 .eslintrc.js ，忽略掉 eslint 对 less 文件的检查
// .eslintrc.cjs
module.exports = {
//...
ignorePatterns: ['dist', '.eslintrc.cjs', '**/*.less'],
}
vscode 配置
在项目根目录创建 .vscode 文件夹，并在文件夹里创建 settings.json 配置文件 这可以让每个使用这个项目的开发人员都能统一 vscode 相关的项目配置
{
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true,
"source.fixAll.stylelint": true,
},
"stylelint.validate": [
"css",
"less",
"postcss"
]
}
添加以上配置， 使文件保存时自动进行 prettier 格式化和 eslint、stylelint 代码检查
commitzen 解决 git commit 信息规范
多人协作项目，git 提交的信息可能就五花八门了，为了提高 git commit 的可读性和可维护性，可以利用 commitzen 这个工具来规范 commit 信息
安装及配置
安装 commitizen 和 cz-customizable 、@commitlint/cli、commitlint-config-cz
// 安装
npm i commitizen cz-customizable @commitlint/cli commitlint-config-cz --save-dev --save-exact
// 初始化配置文件
npx commitizen init cz-customizable
项目根目录创建 .cz-config.cjs 文件，这里一个小知识，为什么是 .cjs 呢
因为我的项目是 ES module。可以看下 package.json，里面有 type: module。
于是 .js 被默认为使用了 ES module 规范，如果自动生成的配置文件使用了 CommonJS，就会出错。.cjs 的 js 会告诉 node.js 它使用了 CommonJS 规范
.cz-config.cjs 配置内容
module.exports = {
// 这里配置type的option值，可自行调整顺序或修改文案
types: [
{
value: 'feat',
name: 'feat(新功能): 向现有功能添加新功能或改进',
},
{
value: 'fix',
name: 'fix(修复): 修复代码库中的bug或者issues',
},
{
value: 'chore',
name: 'chore(任务): 构建/工程依赖/工具/文档更新/格式化',
},
{
value: 'docs',
name: 'docs(文档): 为代码库更新文档',
},
{
value: 'style',
name: 'style(样式): 改善代码库的格式或风格, 修改页面样式',
},
{
value: 'refactor',
name: 'refactor(重构): 对代码库的结构或组织进行重组或改进',
},
{
value: 'perf',
name: 'perf(性能): 代码库性能优化',
},
{
value: 'init',
name: 'init(初始化): 项目初始化',
},
{
value: 'test',
name: 'test(测试): 自动化测试',
},
{
value: 'revert',
name: 'revert(回退): 撤销之前某个提交',
},
{
value: 'build',
name: 'build(构建): 重构系统编译配置',
},
],
// 每一步的提示信息
messages: {
type: '请选择提交类型',
scope: '请选择文件修改范围',
subject: '请输入commit标题(必填)',
body: '请输入commit描述, 可通过&换行(选填)',
// breaking: '列出任何BREAKING CHANGES(破坏性修改)(可选)',
// footer: '请输入要关闭的issue(可选)',
confirmCommit: '确定提交此 commit 吗？',
},
// 配置scope可选项，mono项目可按子项目维度划分，非mono项目可按功能or业务模块划分
scopes: [
{ name: '全局' },
{ name: '账单模块' },
{ name: '用户中心' },
{ name: '登录注册' },
{ name: '其他' },
],
// commit描述的换行符
breaklineChar: '&',
skipQuestions: ['breaking', 'footer'],
// 标题首字母大写
upperCaseSubject: true,
// 标题必填
requiredSubject: true,
};
package.json 文件添加配置
{
"scripts": {
"cz": "cz"
},
"config": {
"commitizen": {
"path": "./node_modules/cz-customizable"
},
"cz-customizable": {
"config": "./.cz-config.cjs"
}
}
}
根目录创建 commitlint.config.cjs 配置
module.exports = {
extends: ['cz'], // commitlint-config-cz 插件 使 commitlint 共享 cz-customizable 配置
rules: {
'type-empty': [2, 'never'],
'subject-empty': [2, 'never'],
'scope-empty': [0],
},
};
最后我们需要配置下 husky 以便将 Commitizen 合并到现有的工作流当中，commitlint 可以校验提交的 commit 信息。
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1}'
现在当你没有按规范填写 commit 信息会在控制台提示
所以我们可以直接使用 npm run cz 来利用交互式命令行提交 commit
总结
- Prettier：用于自动化代码格式化，保持一致的代码风格。
- ESLint：用于静态代码分析，检查和修复 JavaScript 代码中的问题、潜在错误和编码规范。
- Husky 和 lint-staged：用于在 Git 提交前运行代码规范检查，确保只检查更改过的文件。
- Stylelint：用于检查和规范 CSS 代码，确保一致的样式风格。
- VSCode 配置：通过编辑器配置，在保存文件时自动运行 Prettier、ESLint 和 Stylelint，提高代码规范的一致性。
- Commitzen 和 Commitlint：用于规范化 Git 提交信息，使其更易读、易维护，同时通过 Husky 集成，确保提交信息符合规范。
博主自己这套组合拳配置下来，感觉确实还挺麻烦的，但是通过整合这些工具和配置，最后能够让开发团队更轻松的维护代码，减少代码质量问题，我觉得还是值得的。
