基于ESLint+Prettier+Stylelint+git提交规范的团队规范指南

一、ESlint

1、什么是ESLint

EsLint是一个用于识别和报告在 ECMAScript/JavaScript 代码中发现的模式的工具，目的是使代码更加一致，并避免错误。总的来说这就是一个用于代码规范的工具。

2、使用ESLint的好处

对于个人而言它可以避免代码中的语法bug、结构性问题，还能格式化代码和自动美化代码。

对开发团队而言能够统一代码风格，进而降低维护成本，能直接有效的约束团队成员使用统一规范。

3、安装与配置

3.1、安装ESLint

npm install eslint 或 npm install eslint --save-dev

 前者是在运行中使用，如果代码不符合规范，它可能会导致运行时错误或异常。

后者是在开发过程进行检查，语法不错误就不影响运行。

3.2、Vscode安装ESLint的拓展工具

3.3、生成ESLint配置文件

npx eslint --init

  会出现如下配置项进行选择

How would you like to use ESLint? 

//仅检查语法

To check syntax only 

//检查语法和问题

To check syntax and find problems 

//检查语法、发现问题并强制执行代码

To check syntax, find problems, and enforce code style

What type of modules does your project use?

//使用ES6的模块语法

JavaScript modules (import/export)

//使用CommonJS模块规范

CommonJS (require/exports)

//使用其他方式

None of these

//您的项目使用哪个框架？React、Vue.js和其他。

Which framework does your project use?

React

Vue.js

None of these

//您的项目是否使用ts

Does your project use TypeScript? » No / Yes

//您的代码在哪里运行？Browser和Node

Where does your code run?

Browser

Node

//您希望配置文件的格式是什么？JavaScript、YAML和JSON。

What format do you want your config file to be in?

JavaScript

YAML

JSON

//你想要通过哪种方法定义你的代码风格

How would you like to define a style for your project?

//使用流行的代码风格指南
Use a popular style guide

//回答关于你的代码风格的问题
Answer questions about your style

//检查你的 JavaScript 文件
Inspect your JavaScript file(s)

在完成上述的选择后会创建一个配置文件.eslintrc.js（类似如下配置，不同选择配置文件不一样）

module.exports = {"env": {"browser": true,"es2021": true},"extends": ["eslint:recommended","plugin:@typescript-eslint/recommended","plugin:react/recommended"],"overrides": [{"env": {"node": true},"files": [".eslintrc.{js,cjs}"],"parserOptions": {"sourceType": "script"}}],"parser": "@typescript-eslint/parser","parserOptions": {"ecmaVersion": "latest","sourceType": "module"},"plugins": ["@typescript-eslint","react"],"rules": {}
}

3.4、配置文件

配置文件是 ESLint 最主要的配置方式。ESLint 配置文件支持多种格式，同一目录下，ESLint 按 .eslintrc.js, .eslintrc.cjs,  .eslintrc.yaml, .eslintrc.yml, .eslintrc.json, package.json 下的 eslintConfig 字段 的顺序查找配置，相同目录下只有一个配置文件会生效。下面是.eslintrc.js的相关配置及其作用。

// .eslintrc.js
module.exports = {// 规则配置rules: {// 可以根据需要启用、禁用和自定义规则'rule-name': 'error','other-rule': 'warn',},// 解析器配置parser: '@babel/eslint-parser', // 指定使用的解析器//指定直接传递给解析器上的 parse() 或 parseForESLint() 方法的其他选项的对象。parserOptions: {ecmaVersion: 2021, // ECMAScript版本sourceType: 'module', // 模块类型（'script' 或 'module'）ecmaFeatures: {jsx: true, // 启用JSX支持},},// 插件配置plugins: ['plugin-name'], // 配置要使用的插件// 扩展配置extends: ['eslint:recommended', // 使用推荐的ESLint规则'plugin-name/recommended', // 使用指定插件的推荐规则],// 环境配置env: {browser: true, // 浏览器环境node: true, // Node.js环境es6: true, // 启用ES6全局变量},// 全局变量配置globals: {// 可以添加项目中使用的全局变量，避免ESLint报错globalVar: 'readonly',},// 文件过滤器ignorePatterns: ['node_modules/', 'dist/'], // 忽略指定的文件或目录// 其他配置settings: {// 自定义全局变量'import/resolver': {node: {extensions: ['.js', '.jsx'],paths: ['src'], // 自定义模块解析路径},},},// 覆盖特定文件或目录的配置overrides: [{files: ['test/**/*.js'], // 匹配要覆盖的文件rules: {'no-console': 'off', // 关闭在测试文件中禁用控制台的规则},},],// 指定 ESLint 配置文件的根目录root: true,// 禁用在 JavaScript 文件中使用注释行内配置 ESLint 规则noInlineConfig: true,// 在使用了 eslint-disable 注释后报告未使用的禁用指示reportUnusedDisableDirectives: true,// 配置要忽略的文件和目录的匹配模式ignore: ['node_modules/','dist/',],
};

以上是ESLint配置文件的相关配置，各位可以根据自己的需要进行配置，以满足项目的具体要求。

这些配置都可于官方文档中找到，以下我列举几个常用的配置项及其对应参考地址。

rules配置：规则参考 - ESLint 中文网 (nodejs.cn)

 插件配置：配置插件 - ESLint 中文网 (nodejs.cn)

二、 Prettier

1、什么是Prettier

Prettier 是一个代码格式化工具，它可以自动调整代码的缩进、换行和其他样式规范，以使代码风格保持一致。它支持多种编程语言（如 JavaScript、TypeScript、CSS、HTML 等），并且易于集成到各种开发环境和工作流中。

简单说，这个东西它可以一键帮你把代码按规定的格式进行调整美化，以使代码符合对应的规范要求。

2、使用Prettier的好处

Prettier提供了一致的代码风格、提高了开发效率，并减少了代码审查中的样式讨论。它易于配置和集成，适用于各种编程语言和开发环境，是一个值得推荐使用的工具。

3、安装与配置

3.1 VScode插件安装

直接在VScode安装以下插件即可

然后安装如下步骤进行配置即可实现保存自动格式化文件 

1、确保已经在 VS Code 中安装了 Prettier 插件。可以在扩展商店搜索 "Prettier - Code formatter" 并安装。

2、打开 VS Code 的用户设置。可以通过点击菜单栏的 "文件"（File） -> "首选项"（Preferences）-> "设置"（Settings） 或使用快捷键 "Ctrl + ，"（Windows/Linux）或 "Command + ，"（Mac）来打开设置。

3、在设置页面的搜索栏中输入 "format on save"，找到 "Editor: Format On Save" 选项。 勾选 "Editor: Format On Save" 选项，确保其值为 true。这样当你保存文件时，Prettier 将自动对代码进行格式化。

4、（可选）如果你希望在保存时使用 Prettier 进行格式化而不是其他格式化工具，可以添加下面的配置项：

"editor.defaultFormatter": "esbenp.prettier-vscode"

可以选择其他的 Prettier 相关配置项进行个性化设置，如 "prettier.printWidth"、"prettier.tabWidth" 等。

完成以上设置后，每次保存文件时，Prettier 将会自动对代码进行格式化。这样可以确保代码的一致性和可读性，提高开发效率。

3.2 作为依赖安装进项目中

在终端输入以下代码进行安装

npm install prettier -D

4、配置文件

在项目根目录新建一个.prettierrc的文件，格式为json

{"printWidth": 80, // 指定单行代码长度，超过该长度将会进行换行，默认值为 80"tabWidth": 2, // 指定缩进的空格数，默认值为 2"useTabs": false, // 是否使用制表符进行缩进，默认为 false，表示使用空格进行缩进"semi": true, // 是否在语句末尾添加分号，默认为 true"singleQuote": false, // 是否使用单引号，默认为 false，表示使用双引号"quoteProps": "as-needed", // 对象属性是否使用引号包裹，默认为 "as-needed"，表示只有必要时才会添加引号"trailingComma": "none", // 多行数组或对象最后一个元素后是否添加逗号，默认为 "none"，表示不添加"bracketSpacing": true, // 对象字面量中的花括号是否添加空格，默认为 true"arrowParens": "avoid" // 箭头函数的参数是否添加圆括号，默认为 "avoid"，表示只有一个参数时省略圆括号
}

以上为prettier的相关配置，可根据项目需要进行自行调整

三、Stylelint

1、什么是Stylelint

Stylelint 是一个强大、先进的 CSS 代码检查器，可以帮助你规避 CSS 代码中的错误并保持一致的编码风格。

2、使用Stylelint的好处

1、提高代码质量：Stylelint是一款用于检查CSS代码的工具，可以帮助开发者找出代码中的潜在问题、错误和不规范的写法。通过使用StyleLint，开发者可以在编写CSS代码时遵循一些固定的规则和标准，从而提高代码的质量。

2、统一代码风格：Stylelint支持自定义规则集，可以根据项目需要进行相应的配置。通过统一代码风格，可以让团队成员之间的代码风格更加一致，便于后续代码的维护和修改。

3、提高代码可读性：Stylelint可以对代码进行格式化，使其更加易读、易懂。通过规范的代码格式，可以使代码更容易被其他人理解和阅读，从而提高代码可读性。

4、简化代码维护：Stylelint可以自动修复一些问题，例如错误的缩进、空格等等。通过自动修复这些问题，可以减少手动修复的时间，从而简化代码维护的过程。

3、安装与配置

3.1 VScode插件安装

 

1. 打开VSCode，进入扩展面板（快捷键为Ctrl+Shift+X或者Cmd+Shift+X），搜索Stylelint插件。

2. 选择Stylelint插件并进行安装。

3. 安装完成后，在VSCode的设置（快捷键为Ctrl+,或者Cmd+,）中搜索stylelint.enable，将其设置为true，以启用Stylelint插件。

4. 在VSCode的设置中搜索stylelint.config，指定Stylelint配置文件的路径。如果你的配置文件为.stylelintrc.json，则可以设置为：

{ "stylelint.config": ".stylelintrc.json" }

通过安装Stylelint插件，你可以在VSCode中方便地使用Stylelint来检查你的CSS代码，提高代码规范性和可维护性。

3.2 作为依赖安装进项目中

在终端输入以下代码进行stylelint（核心包）和stylelint-config-standard（StyleLint推荐标准配置）的安装

npm install stylelint stylelint-config-standard --save-dev

在根目录下创建名为 .stylelintrc.js 的文件用于放置StyleLint的配置信息，可以添加如下内容

module.exports = {extends: ['stylelint-config-recommended','stylelint-config-prettier'], // 继承基本配置和Prettier插件的配置plugins: ['stylelint-order','stylelint-declaration-block-no-ignored-properties'], // 加载自定义插件rules: {'color-hex-case': 'lower', // 颜色值使用小写字母'color-hex-length': 'long', // 颜色值使用长格式'font-family-name-quotes': 'always-where-recommended', // 字体名称使用引号'function-comma-newline-after': 'always-multi-line', // 多行函数逗号后面必须换行'function-comma-space-after': 'always-single-line', // 单行函数逗号后面必须空格'function-name-case': 'lower', // 函数名称使用小写字母'function-url-quotes': 'always', // 函数URL使用引号'max-nesting-depth': 3, // 最大嵌套深度为3'no-empty-source': true, // 不允许空的样式文件'order/properties-order': [], // CSS属性排序规则'property-no-unknown': [ // 不允许未知属性true,{ignoreProperties: ['composes']}],'selector-max-id': 0, // 不允许使用ID选择器'selector-pseudo-element-no-unknown': [ // 不允许未知的伪元素true,{ignorePseudoElements: ['v-deep']}],'selector-type-no-unknown': [ // 不允许未知的元素类型选择器true,{ignoreTypes: ['/^v-/']}]}
}

 以上为Stylelint的相关配置，可根据项目需要进行自行调整。

四、git提交规范（commitlint+lint-staged+husky）

1、Commitlint

1.1 什么时Commitlint

在我们开发完成后提交代码时，通常都需要填写提交说明，此提交说明用于git查看历史提交时使用直接的展现每次提交对于项目的更改，为了禁止不符合规范的提交，我们就需要采用一些工具，只有当开发者编写了符合规范的提交说明才能够进行 提交。而 Commitlint 就是这样一种工具，通过结合 husky 一起使用，可以在开发者进行 commit 前就对提交说明进行检查，只有符合规范，才能够进行 commit。

1.2 Commitlint的安装与配置

使用npm安装Commitlint

npm install @commitlint/cli @commitlint/config-conventional --save-dev

安装完成后再根目录创建.commitlintrc.js文件进行配置。

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

 2、Husky

2.1 什么是Husky

在谈Husky需要先了解一下Git Hook在客户端部分的一些操作，主要分为以下这四种：

pre-commit：在代码提交前进行的操作，比如检查相关规范，检查语法等，用于防止提交错误的代码。

prepare-commit-msg：在你写commit信息之前，可以自动设置默认的commit信息，比如添加分支名称、任务ID等，方便你写commit信息。

commit-msg：在你提交commit信息之前，可以自动检查commit信息是否符合规范，比如检查是否包含必要的标识、长度限制等，确保commit信息的规范性。

post-commit：在你提交完代码之后，可以让计算机自动执行一些后续操作，比如自动推送代码到远程仓库，方便你管理代码。

在了解完以上的信息之后，我们来介绍一下Husky——Git Hook工具。主要用于配置和管理Git Hook脚本。它为开发者提供了一种简单的方式，在项目中添加和管理Git Hook脚本，无需手动编写和维护。

Husky主要作用在Git Hook的pre-commit、commit-msg等部分。它可以帮助你在项目中快速设置和执行Git Hook脚本，使得你可以在代码提交、合并等操作中加入额外的检查和验证。它与pre-commit、commit-msg等Git Hook脚本结合使用，让你可以在代码提交前运行代码格式化工具、静态代码分析工具、单元测试等，以确保提交的代码质量。

2.2 Husky的安装与配置

使用npm安装Husky

npm install husky --save-dev

在安装完成后需要对 package.json 文件进行配置

"scripts": {"prepare": "husky install",
},

在配置完成后在终端输入如下代码

 npm run prepare

指令执行成功后会在项目根目录下面生成一个 .husky 目录，该目录下有一个 _ 目录。

然后在终端输入如下代码创建 commit-msg 文件

npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

该文件的作用是 git commit 前执行一下 npx --no -- commitlint --edit $1 指令，对 commit 的注释进行校验。

然后输入以下代码创建 pre-commit 文件

npx husky add .husky/pre-commit "npm run lint-staged"

该文件的作用主要是用于在git commit前执行 npm run lint-staged 指令，对代码进行规范的校验，不符合规范就终止commit。

然后在package.json加入如下代码（ps：要在ESLint和Stylelint安装配置好后进行）

  "lint-staged": {"src/**/*.{js,ts,vue}": "eslint --fix --ignore-path .eslintignore","src/**/*.{less,sass,css,vue}": "stylelint --fix --ignore-path .eslintignore"}

 但是如果只有Husky的话，每次提交代码都会对所有文件运行Lint检查，如果项目体量大，那所耗费的时间成本太大了，为了解决这个问题，我们需要结合下面的工具Lint-staged进行使用。

3、Lint-staged

3.1 什么是Lint-staged

Lint-staged 可以在我们运行 ESlint 或 Stylelint 命令时，可以通过设置指定只检查我们通过 git add 添加到暂存区的文件，可以避免我们每次检查都把整个项目的代码都检查一遍，从而提高效率。

其次，Lint-staged 允许指定不同类型后缀文件执行不同指令的操作，并且可以按步骤再额外执行一些其它 shell 指令。

3.2 安装和配置Lint-staged

使用npm安装Lint-staged

npm install lint-staged --save-dev

在安装完 Lint-staged后在package.json加入如下代码进行配置（ps：要在husky，ESLint 和 Stylelint安装配置完后操作）

"scripts": {"prepare": "husky install",},"husky": {"hooks": {"pre-commit": "lint-staged"}},"lint-staged": {"*.{js,jsx,ts,tsx}": ["eslint --fix","prettier --write"],"*.json": ["prettier --write"],"*.vue": ["eslint --fix","prettier --write","stylelint --fix"],"*.{scss,less,html}": ["stylelint --fix","prettier --write"],"*.md": ["prettier --write"]}

当我们执行 git commit 时，就会触发 husky 的 pre-commit 钩子，调用 lint-staged 命令。而 lint-staged会根据配置对不同类型的文件进行规范检查。

五、配置实例

1、ESLint配置实例

以下是团队的ESLint的配置实例

//.eslintrc.js
module.exports = {//指定使用 @typescript-eslint/parser 解析器，以解析 TypeScript 代码。parser: '@typescript-eslint/parser',
//继承了一些预设的规则集，提供了一系列的规则配置，可以帮助你更好地检测和修复代码中的问题。extends: ['plugin:@typescript-eslint/recommended', 'react-app', 'plugin:prettier/recommended'],//引入了一些插件,提供了额外的规则和功能，可以进一步增强 ESLint 的能力。plugins: ['@typescript-eslint', 'react'],//定义了一些具体的规则配置。rules: {//使用 Prettier 进行代码格式化，并将格式不一致的代码视为错误。'prettier/prettier': 'error',//禁止未使用的变量。'@typescript-eslint/no-unused-vars': 'error',//允许使用 any 类型。'@typescript-eslint/no-explicit-any': 'off',//允许使用 TypeScript 的注释语法。'@typescript-eslint/ban-ts-comment': 'off',//允许使用全局变量。'no-restricted-globals': 'off',//允许使用非空断言操作符（!）。'@typescript-eslint/no-non-null-assertion': 'off',},
};

用以下文件来设置规则忽略的文件 

//.eslintignore
config/
node_modules/

2、prettier配置实例

以下是团队的prettier配置实例

// .prettierrc.js
module.exports =  {"printWidth": 120,"semi": true,"singleQuote": true,"tabWidth": 2,"endOfLine": 'auto'};

3、Stylelint配置实例 

以下是团队的Stylelint配置实例

//.stylelintrc.js
module.exports = {processors: [],plugins: ['stylelint-order'],extends: ["stylelint-config-standard","stylelint-config-css-modules"],rules: {"indentation": 2,"no-descending-specificity": null,"selector-class-pattern": null}
}

4、git提交规范配置

以下是团队的git提交规范配置实例

//package.json
"scripts": {"lint": "eslint --ext .js,.jsx,.ts,.tsx ./src","lint:fix": "eslint --ext .js,.jsx,.ts,.tsx ./src --fix","lint:less": "stylelint src/**/*.less --custom-syntax postcss-less","lint:less:fix": "stylelint src/**/*.less --fix  --custom-syntax postcss-less","prepare": "husky install"},"husky": {"hooks": {"pre-commit": "lint-staged"}},"lint-staged": {"*.{ts,tsx}": ["npm run lint:fix","git add"],"*.less": ["npm run lint:less:fix","git add"]},"devDependencies": {"husky": "^8.0.3"}