Mydoc

外观

随着前端应用逐渐变得大型化和复杂化，在同一个项目中有多个人员参与时，每个人的前端能力程度不等，他们往往会用不同的编码风格和习惯在项目中写代码，长此下去，势必会让项目的健壮性越来越差。解决这些问题，理论上讲，口头约定和代码审查都可以，但是这种方式无法实时反馈，而且沟通成本过高，不够灵活，更关键的是无法把控。不以规矩，不能成方圆，我们不得不在项目使用一些工具来约束代码规范。
下面讲解如何使用 EditorConfig + Prettier + ESLint 组合来实现代码规范化。
这样做带来好处：

  • 解决团队之间代码不规范导致的可读性差和可维护性差的问题。
  • 解决团队成员不同编辑器导致的编码规范不统一问题。
  • 提前发现代码风格问题，给出对应规范提示，及时修复。
  • 减少代码审查过程中反反复复的修改过程，节约时间。
  • 自动格式化，统一编码风格，从此和脏乱差的代码说再见。

集成 EditorConfig 配置 ​

EditorConfig 有助于为不同 IDE 编辑器上处理同一项目的多个开发人员维护一致的编码风格。
官网：editorconfig.org
在项目根目录下增加 .editorconfig 文件：

# Editor configuration, see http://editorconfig.org

# 表示是最顶层的 EditorConfig 配置文件
root = true

[*] # 表示所有文件适用
charset = utf-8 # 设置文件字符集为 utf-8
indent_style = space # 缩进风格（tab | space）
indent_size = 2 # 缩进大小
end_of_line = lf # 控制换行类型(lf | cr | crlf)
trim_trailing_whitespace = true # 去除行首的任意空白字符
insert_final_newline = true # 始终在文件末尾插入一个新行

[*.md] # 表示仅 md 文件适用以下规则
max_line_length = off
trim_trailing_whitespace = false
# Editor configuration, see http://editorconfig.org

# 表示是最顶层的 EditorConfig 配置文件
root = true

[*] # 表示所有文件适用
charset = utf-8 # 设置文件字符集为 utf-8
indent_style = space # 缩进风格（tab | space）
indent_size = 2 # 缩进大小
end_of_line = lf # 控制换行类型(lf | cr | crlf)
trim_trailing_whitespace = true # 去除行首的任意空白字符
insert_final_newline = true # 始终在文件末尾插入一个新行

[*.md] # 表示仅 md 文件适用以下规则
max_line_length = off
trim_trailing_whitespace = false

注意：

  • VSCode 使用 EditorConfig 需要去插件市场下载插件 EditorConfig for VS Code 。
  • JetBrains 系列（WebStorm、IntelliJ IDEA 等）则不用额外安装插件，可直接使用 EditorConfig 配置。

集成 Prettier 配置 ​

Prettier 是一款强大的代码格式化工具，支持 JavaScript、TypeScript、CSS、SCSS、Less、JSX、Angular、Vue、GraphQL、JSON、Markdown 等语言，基本上前端能用到的文件格式它都可以搞定，是当下最流行的代码格式化工具。
官网：prettier.io/

  1. 安装 Prettier
bash
npm i prettier -D
npm i prettier -D
  1. 创建 Prettier 配置文件

Prettier 支持多种格式的配置文件，比如 .json、.yml、.yaml、.js 等。
在本项目根目录下创建 .prettierrc 文件。

  1. 配置 .prettierrc 在本项目中，我们进行如下简单配置，关于更多配置项信息，请前往官网查看 Prettier-Options 。
json
{
	"useTabs": false,
	"tabWidth": 2,
	"printWidth": 100,
	"singleQuote": true,
	"trailingComma": "none",
	"bracketSpacing": true,
	"semi": false
}
{
	"useTabs": false,
	"tabWidth": 2,
	"printWidth": 100,
	"singleQuote": true,
	"trailingComma": "none",
	"bracketSpacing": true,
	"semi": false
}
  1. Prettier 安装且配置好之后，就能使用命令来格式化代码
bash
# 格式化所有文件（. 表示所有文件）
npx prettier --write .
# 格式化所有文件（. 表示所有文件）
npx prettier --write .

注意：

  • VSCode 编辑器使用 Prettier 配置需要下载插件 Prettier - Code formatter 。

  • JetBrains 系列编辑器（WebStorm、IntelliJ IDEA 等）则不用额外安装插件，可直接使用 Prettier 配置。

Prettier 配置好以后，在使用 VSCode 或 WebStorm 等编辑器的格式化功能时，编辑器就会按照 Prettier 配置文件的规则来进行格式化，避免了因为大家编辑器配置不一样而导致格式化后的代码风格不统一的问题。

解决 Prettier 和 ESLint 的冲突 ​

通常大家会在项目中根据实际情况添加一些额外的 ESLint 和 Prettier 配置规则，难免会存在规则冲突情况。
项目中的 ESLint 配置中使用了 Airbnb JavaScript 风格指南校验，其规则之一是代码结束后面要加分号，而我们在 Prettier 配置文件中加了代码结束后面不加分号的配置项，这样就有冲突了，会出现用 Prettier 格式化后的代码，ESLint 检测到格式有问题的，从而抛出错误提示。
解决两者冲突问题，需要用到 eslint-plugin-prettier 和 eslint-config-prettier。

  • eslint-plugin-prettier 将 Prettier 的规则设置到 ESLint 的规则中。
  • eslint-config-prettier 关闭 ESLint 中与 Prettier 中会发生冲突的规则。

最后形成优先级：Prettier 配置规则 > ESLint 配置规则。

  • 安装插件
bash
npm i eslint-plugin-prettier eslint-config-prettier -D
npm i eslint-plugin-prettier eslint-config-prettier -D
  • 在 .eslintrc.js 添加 prettier 插件
typescript
module.exports = {
  ...
  extends: [
    'plugin:vue/essential',
    'airbnb-base',
    'plugin:prettier/recommended' // 添加 prettier 插件
  ],
  ...
}
module.exports = {
  ...
  extends: [
    'plugin:vue/essential',
    'airbnb-base',
    'plugin:prettier/recommended' // 添加 prettier 插件
  ],
  ...
}

这样，我们在执行 eslint --fix 命令时，ESLint 就会按照 Prettier 的配置规则来格式化代码，轻松解决二者冲突问题。

集成 husky 和 lint-staged ​

配置 husky ​

使用 husky-init 命令快速在项目初始化一个 husky 配置。

bash
npx husky-init && npm install
npx husky-init && npm install

这行命令做了四件事：

  1. 安装 husky 到开发依赖
  2. 在项目根目录下创建 .husky 目录
  3. 在 .husky 目录创建 pre-commit hook，并初始化 pre-commit 命令为 npm test
  4. 修改 package.json 的 scripts，增加 "prepare": "husky install"

**特别注意：本项目使用 husky 6.x 版本，6.x 版本配置方式跟之前的版本有较大差异。目前网上大部分有关 husky 的教程都是 6 以前的版本 ，当发现配置方法不一致时，一切以 **husky 官网为准。

到这里，husky 配置完毕，现在我们来使用它：
husky 包含很多 hook（钩子），常用有：pre-commit、commit-msg、pre-push。这里，我们使用 pre-commit 来触发 ESLint 命令。
修改 .husky/pre-commit hook 文件的触发命令：

bash
eslint --fix ./src --ext .vue,.js,.ts
eslint --fix ./src --ext .vue,.js,.ts

上面这个 pre-commit hook 文件的作用是：当我们执行 git commit -m "xxx" 时，会先对 src 目录下所有的 .vue、.js、.ts 文件执行 eslint --fix 命令，如果 ESLint 通过，成功 commit，否则终止 commit。

但是又存在一个问题：有时候我们明明只改动了一两个文件，却要对所有的文件执行 eslint --fix。假如这是一个历史项目，我们在中途配置了 ESLint 规则，那么在提交代码时，也会对其他未修改的“历史”文件都进行检查，可能会造成大量文件出现 ESLint 错误，显然不是我们想要的结果。

我们要做到只用 ESLint 修复自己此次写的代码，而不去影响其他的代码。所以我们还需借助一个神奇的工具 lint-staged 。

配置 lint-staged ​

lint-staged 这个工具一般结合 husky 来使用，它可以让 husky 的 hook 触发的命令只作用于 git add那些文件（即 git 暂存区的文件），而不会影响到其他文件。

接下来，我们使用 lint-staged 继续优化项目。

  1. 安装 lint-staged
bash
npm i lint-staged -D
npm i lint-staged -D
  1. 在 package.json里增加 lint-staged 配置项
    这行命令表示：只对 git 暂存区的 .vue、.js、.ts 文件执行 eslint --fix。
json
"lint-staged": {
  "*.{vue,js,ts}": "eslint --fix"
},
"lint-staged": {
  "*.{vue,js,ts}": "eslint --fix"
},
  1. 修改 .husky/pre-commit hook 的触发命令为：npx lint-staged

至此，husky 和 lint-staged 组合配置完成。

现在我们提交代码时就会变成这样：

假如我们修改了 scr 目录下的 test-1.js、test-2.ts 和 test-3.md 文件，然后 git add ./src/，最后 git commit -m "test..."，这时候就会只对 test-1.js、test-2.ts 这两个文件执行 eslint --fix。如果 ESLint 通过，成功提交，否则终止提交。从而保证了我们提交到 Git 仓库的代码都是规范的。

  • 提交前 test-1.js、test-2.ts
  • 提交后 test-1.js、test-2.ts 自动修复代码格式

无论写代码还是做其他事情，都应该用长远的眼光来看，刚开始使用 ESint 的时候可能会有很多问题，改起来也很费时费力，只要坚持下去，代码质量和开发效率都会得到提升，前期的付出都是值得的。

这些工具并不是必须的，没有它们你同样可以可以完成功能开发，但是利用好这些工具，你可以写出更高质量的代码。特别是一些刚刚接触的人，可能会觉得麻烦而放弃使用这些工具，失去了一次提升编程能力的好机会。