前端代码规范最佳实践：eslint + prettier + editorconfig + lint-staged + vscode的settings.json文件

prettierrc常用配置

{
    "printWidth": 200,
    "tabWidth": 4,
    "useTabs": false,
    "semi": true,
    "singleQuote": true,
    "jsxSingleQuote": true,
    "bracketSpacing": true,
    "arrowParens": "avoid",
    "eslintIntegration": true,
    "trailingComma": "none"
}

{
“printWidth”: 200, // 超过最大值换行
“tabWidth”: 4, // 缩进字节数
“useTabs”: false, // 缩进不使用tab，使用空格
“semi”: true, / 句尾添加分号
“singleQuote”: true, // 使用单引号代替双引号
“bracketSpacing”: true, // 在对象，数组括号与文字之间加空格 “{ foo: bar }”
“arrowParens”: “avoid”, // (x) => {} 箭头函数参数只有一个时是否要有小括号。avoid：省略括号
“eslintIntegration”: true, // 让prettier使用eslint的代码格式进行校验
“trailingComma”: “none” // 在对象或数组最后一个元素后面是否加逗号
}

---

前言

项目开发过程中，用到各种代码规范性工具。

时不时就会出现，多种工具重复作用，相互之间有冲突的情况。

比如：按照 prettier 的规则格式化的代码，不符合 eslint 的规定。于是 eslint 报错。

一、开始做事之前，先明确目的

问自己一个问题：为项目配置代码规范，要达到什么目的？

【答案】

1.开发过程中，如果写出不符合我们规范的代码，能够及时提醒开发者，便于及时修复（eslint的能力）

2.保存/粘贴代码时、使用格式化快捷键时，能够自动按照我们制定的规范、格式化代码（prettier的能力）

3.不同开发者如果使用不同的编辑器（sublime/vscode）或系统（windows/mac），能够执行统一的代码风格标准。比如：缩进是tab还是space，结尾end_of_line是lf还是crlf（editorconfig的能力 —— 用于覆盖编辑器的默认配置）

二、再次明确 eslint、prettier、editorconfig 各自能力

1.eslint

官网

通过配置 .eslintrc.* 制定团队代码规范。在代码编写的过程中，出现不符合规范的代码，进行红线提示。帮助开发者及时更正不符合规范的代码。同时，提供命令行检查规范及 auto-fix 能力。

【具体】

检查 main.js 文件的代码规范：

npx eslint main.js

自动修复 main.js 部分规范问题（通常如：缺少/多余分号，缩进格式等）：

npx eslint main.js --fix

【注意】

eslint 的 auto-fix，能够修复的规范问题比较有限。

通常，需要较大变动才能修复的规范问题，eslint 无法自动修复。如：单行不能超过 80 个字符。

.eslintrc配置文件与VSCode中eslint插件的关系

VSCode 的 ESLint 插件依赖于项目的 .eslintrc 文件来获取规则配置，如果项目中没有 .eslintrc 文件，插件可能会使用默认的 ESLint 配置。

如果你不安装 VSCode 的 ESLint 插件，ESLint 依然可以在你的项目中独立运行，但是1、需要通过命令手动运行 ESLint 来检查代码。通常使用 npx eslint .命令来检查整个项目。
2、缺少实时反馈与开发体验：没有插件，你在编写代码时不会获得实时的错误和警告提示。这意味着你可能会在提交代码之前才发现存在的问题，影响开发效率。

总之，没有安装 ESLint 插件并不影响 ESLint 的基本功能，因为 ESLint 本身是独立的命令行工具。然而，插件的存在极大地提升了开发者的效率和体验，特别是在大型项目或团队协作中。

2.prettier

prettier引擎提供了代码修复能力，vscode提供了prettier插件，可以通过这个插件的能力来进行格式化，而不是必须通过命令来进行。但是这个插件底层还是依赖prettier引擎。

---

根据规范，自动格式化代码。具有比 eslint auto-fix 更加强大的代码规范性修复能力。

npx prettier main.js --write

prettier 会根据 .prettierrc* 的约定，修复 main.js 的规范性问题。包括较大变动才能修复的规范问题。如：单行不能超过 80 个字符，增加分号等。

3.editorconfig

编辑器配置。用于覆盖编辑器默认配置，以确保不同编辑器之间，代码格式的统一。

比如，使用 editorconfig，规定开发过程中，按键 tab 按钮，是以 tab 格式进行缩进，还是以 space 格式进行缩进。

如果没有约定，不同的编辑器，或者相同编辑器、不同开发者的配置存在差异，可能出现，有的人是 tab 缩进、有的人是 space 缩进的情况，造成代码风格的差异。

【注】vscode 这类编辑器，需要自行安装 editorconfig 插件，才会读取.editorconfig配置，进而改变行为。

4. settings.json是什么?对VS Code有什么用？

settings.json文件是VS Code众多“配置文件”中的一个，用来控制诸多工作项的配置。

按快捷键【Ctrl】+【,】，打开VS Code的设置界面，

可以看到设置内容有“用户” “工作区”两个分支，它们其实就分别对应了两个不同位置的settings.json文件，前者位于与用户相关联的特定文件夹中，后者就会位于你当前打开的文件夹的.vscode子目录下。这两个settings.json文件其实都只会包含你修改过的设置项，而软件的全局默认设置则记录在软件安装目录中的某个位置，用户是不必理会的。

这些配置文件具有工作区 用户 全局默认 的优先级，前面的配置覆盖后面的，这样做的好处是你可以为不同工作区、不同用户做不同配置，而不会互相干扰。而当你不小心在某个工作区做了错误的配置导致软件不能正常工作时，只需删除相应的设置项，或者settings.json文件，即可恢复到用户配置或默认配置。

早期的时候VS Code开发尚不完善时，是没有UI形式的设置界面的，那时全凭json文件自定义配置。现在的Sublime等著名编辑器也在使用这种配置方法。

三、进行配置（js文件）

1.安装 eslint + prettier

yarn add eslint prettier -D

安装 eslint-config-prettier

yarn add eslint-config-prettier -D

【作用】

让所有可能会与 prettier 规则存在冲突的 eslint rule，失效，并使用 prettier 的规则进行代码检查。

相当于，用 prettier 的规则，覆盖掉 eslint:recommended 的部分规则。

后面 prettier 格式化，也会根据这个规则来。因此，不会再有冲突。

【使用】

.eslintrc.js

{
    "extends": ["eslint:recommended", "prettier"]
}

3.安装 eslint-plugin-prettier

yarn add eslint-plugin-prettier -D

【作用】

将 prettier 的能力集成到 eslint 中。按照 prettier 的规则检查代码规范性，并进行修复。

【使用】

.eslintrc.js

{
    "rules":{
        "prettier/prettier":"error" // 不符合 prettier 规则的代码，要进行错误提示（红线）
    },

    "plugins": ["prettier"]
}

或

{
    "extends": ["eslint:recommended","plugin:prettier/recommended"]
}

【看一下效果】

npx eslint --fix main.js

至此，eslint 会拥有和 prettier 一样的修复能力。

像 prettier 一样，格式化所有不符合规范的代码。

四、ESLint和Prettier的区别：

4.1 ESLint

ESLint 是什么呢？是一个开源的 JavaScript 的 linting 工具，使用 espree 将 JavaScript 代码解析成抽象语法树 (AST)，然后通过AST 来分析我们代码，从而给予我们两种提示：

1. 代码质量问题：使用方式有可能有问题(problematic patterns)
2. 代码风格问题：风格不符合一定规则 (doesn’t adhere to certain style guidelines)

rules: {
        'react/destructuring-assignment': 0,
        'object-curly-newline': 'off'
    }

4.2 Prettier

上面我们说到，ESLint 主要解决了两类问题，但其实 ESLint 主要解决的是代码质量问题。另外一类代码风格问题其实 Airbnb JavaScript Style Guide 并没有完完全全做完，因为这些问题"没那么重要"，代码质量出问题意味着程序有潜在 Bug，而风格问题充其量也只是看着不爽。

这时候就出现了 Prettier，Prettier 声称自己是一个有主见 (偏见) 的代码格式化工具 (opinionated code formatter)，Prettier 认为格式很重要，但是格式好麻烦，我来帮你们定好吧。简单来说，不需要我们再思考究竟是用 single quote，还是 double quote 这些乱起八糟的格式问题，Prettier 帮你处理。最后的结果，可能不是你完全满意，但是，绝对不会丑，况且，Prettier 还给予了一部分配置项，可以通过 .prettierrc 文件修改。

所以相当于 Prettier 接管了两个问题其中的代码格式的问题，而使用 Prettier + ESLint 就完完全全解决了两个问题。但实际上使用起来配置有些小麻烦，但也不是什么大问题。因为 Prettier 和 ESLint 一起使用的时候会有冲突。这些冲突可以通过上面的 三、进行配置（js文件） 来进行解决

五、使用编辑器，自动格式化代码

1. 使用自己编辑器的快捷键，格式化代码

   以 vscode 为例：shift + option + f

   默认格式化规则选择 prettier，即可完成代码格式化。

2. 保存代码，自动格式化
   同样以 vscode 为例，打开你的 settings.json，添加下面这句话：

"editor.formatOnSave": true

【注】

至此，js、json、less等文件，均可实现自动格式化。

文件格式化规则，遵从我们在 .eslintrc.js 里的配置。也就是，使用我们的 prettier 插件默认规则去格式化。

【附】

如果你使用的是 webstorm，或许可以参考这个 https://www.jianshu.com/p/2f3cad152192

六、规范检查增强（husky + lint-staged）

在 git commit 之前，先强制执行prettier格式化（防止某些成员开发期间不开启编辑器格式化）、再检查代码规范，如果检查不通过、阻止提交。

6. 1.新建 .eslintignore + .prettierignore

.eslintignore、.prettierignore，参考如下：

.DS_Store
node_modules
dist
.gitignore
.eslintignore
.prettierignore
LICENSE
README.md
yarn.lock
# local env files
.env.local
.env.*.local
# Log files
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Editor directories and files
.idea
.vscode
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?

6.2 安装

yarn add husky lint-staged -D

6.3 使用

package.json添加：

"scripts": {
    "lint": "eslint --fix",
    "prettier": "prettier --config .prettierrc --write"
},
"husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
   "src/**.{js,jsx}": [
        "npm run prettier", 
        "npm run lint",
        "git add ."
    ]
  }

git commit 之前，会自动使用 prettier 格式化 ignore 之外的代码。格式化后，自动检查所有文件，是否全部符合 eslint 规范。

存在不符合规范的代码，git commit 将被终止。

【注】

因为 prettier 只是会帮我们格式化代码，并不能够修复所有 eslint 错误，比如定义未使用的变量，prettier 不会自动帮我们删除，要手动删除。

因此，prettier 后再 eslint，是有必要的。

---

七：提交信息commit-msg检查（husky + commit-msg）

参考链接：https://blog.csdn.net/qq_38290251/article/details/111646491
commitlint是一个开源的git commit -m “msg” msg的提交规范库，使用 commitlint 可以规范我们每一次的 commit，我们可以用来自动生成 changeLog 等文件，方便代码管理。

1. 安装husky

1、安装链接：https://typicode.github.io/husky/zh/get-started.html，注意V4后语法和之前存在差异。

npx husky init

之后，husky会自动在package.json的scripts创建"prepare": "husky"命令，目的是在安装依赖时能够完成对 Git hooks 的设置。
2、创建commit-msg

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

备注：如果创建失败，则自行创建文件。在执行 commitlint 时，只会使用本地已经安装的 commitlint，而不会尝试从 npm 下载和安装它。如果 commitlint 不存在于本地环境中，这个命令将失败。

在huskey的commit-msg中添加脚本：

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx --no-install commitlint --edit "$1"
node scripts/commit-msg.js

创建 scripts/commit-msg.js文件

const fs = require('fs');
const Path = require('path');
// 定义提交信息的正则表达式
const commitMsgPattern = /^[^:]+: [^\s]+(模块|页面)-[^\s]+/;
try {
    let message = fs.readFileSync(Path.resolve(__dirname, '../.git/COMMIT_EDITMSG'), 'utf-8');
    console.log('message', message);
    if (!commitMsgPattern.test(message)) {
        console.error('提交信息格式错误。正确格式为：<type>: <xxx模块或页面-xxx功能描述>');
        process.exit(1);
    }
} catch (e) {
    console.log('检测程序运行出错...', e);
}

3、配置commitlint

module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "type-enum": [2, "always", ["feat", "fix", "refactor", "chore", "docs", "style", "test"]], // 允许的类型 
    "subject-case": [2, "always", "lower-case"], // 主题部分强制小写 
    "subject-full-stop": [2, "never", "."], // 禁止以句号结尾 
  },
};

八：根据 commit message 自动生成 changelog

约定式提交：https://www.conventionalcommits.org/zh-hans/v1.0.0/

使用

参考 conventional-changelog

1. 安装依赖

npm install conventional-changelog conventional-changelog-cli --save-dev

2. 添加脚本

{
  "scripts": {
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
  }
}

3. 生成CHANGELOG.md文件
   直接运行下面的命令即可

npm run changelog

如果type为feat、fix、perf、revert，则该 commit 将肯定出现在 Change log 之中。其他情况（docs、chore、style、refactor、test）由你决定，要不要放入 Change log，建议是不要。

注意：版本的log使用 npm version 才会生成新的log，手动修改 package.json version 不会有新的版本log。
npm version [ | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]

参考npm version：https://docs.npmjs.com/cli/v8/commands/npm-version

npm version 命令用于更新和设置包的版本号，并可以自动创建并提交Git标签以及更新package.json文件。该命令的语法如下：

npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]

每个参数的含义如下：

• <newversion>：这是一个可选的参数，表示你要将包的版本号更新为的具体版本号。可以是任何有效的版本号，如1.2.3。如果提供了这个参数，它将直接设置包的版本号为指定的值。

• major：这是一个可选的参数，表示要执行主版本号升级。执行此命令后，包的主版本号将加1，次版本号和修订号将重置为0。

• minor：这是一个可选的参数，表示要执行次版本号升级。执行此命令后，包的次版本号将加1，修订号将重置为0。

• patch：这是一个可选的参数，表示要执行修订号升级。执行此命令后，包的修订号将加1。

• premajor：这是一个可选的参数，表示要执行主版本号升级，并在版本号后添加一个预发布标签（如-alpha.1）。

• preminor：这是一个可选的参数，表示要执行次版本号升级，并在版本号后添加一个预发布标签。

• prepatch：这是一个可选的参数，表示要执行修订号升级，并在版本号后添加一个预发布标签。

• prerelease：这是一个可选的参数，表示要在当前版本号的基础上添加一个预发布标签。

• from-git：这是一个可选的参数，用于根据最新的Git提交信息自动确定新版本号。这可以用于生成一个语义版本号，根据Git提交历史中的特性和修复来决定。

npm version 命令通常用于升级包的版本号，并且在升级后，它会自动创建一个Git标签，以及在package.json中更新新的版本号。你可以根据项目需求选择不同的参数来执行不同类型的版本升级和预发布标签。

通过使用npm 钩子，可以做一些自动化的东西，例如：

{
  "scripts": {
    "preversion": "npm test",
    "version": "npm run build && git add -A dist",
    "postversion": "git push && git push --tags && rm -rf build/temp"
  }
}

4. 自定义conventional-changelog

const compareFunc = require('compare-func')
module.exports = {
  writerOpts: {
    transform: (commit, context) => {
      let discard = true
      const issues = []

      commit.notes.forEach(note => {
        note.title = 'BREAKING CHANGES'
        discard = false
      })
      if (commit.type === 'feat') {
        commit.type = '✨ Features | 新功能'
      } else if (commit.type === 'fix') {
        commit.type = '🐛 Bug Fixes | Bug 修复'
      } else if (commit.type === 'perf') {
        commit.type = '⚡ Performance Improvements | 性能优化'
      } else if (commit.type === 'revert' || commit.revert) {
        commit.type = '⏪ Reverts | 回退'
      } else if (discard) {
        return
      } else if (commit.type === 'docs') {
        commit.type = '📝 Documentation | 文档'
      } else if (commit.type === 'style') {
        commit.type = '💄 Styles | 风格'
      } else if (commit.type === 'refactor') {
        commit.type = '♻ Code Refactoring | 代码重构'
      } else if (commit.type === 'test') {
        commit.type = '✅ Tests | 测试'
      } else if (commit.type === 'build') {
        commit.type = '👷‍ Build System | 构建'
      } else if (commit.type === 'ci') {
        commit.type = '🔧 Continuous Integration | CI 配置'
      } else if (commit.type === 'chore') {
        commit.type = '🎫 Chores | 其他更新'
      }


      if (commit.scope === '*') {
        commit.scope = ''
      }
      if (typeof commit.hash === 'string') {
        commit.hash = commit.hash.substring(0, 7)

      }
      if (typeof commit.subject === 'string') {
        let url = context.repository
          ? `${context.host}/${context.owner}/${context.repository}`
          : context.repoUrl
        if (url) {
          url = `${url}/issues/`
          // Issue URLs.
          commit.subject = commit.subject.replace(/#([0-9]+)/g, (_, issue) => {
            issues.push(issue)
            return `[#${issue}](${url}${issue})`
          })
        }
        if (context.host) {
          // User URLs.
          commit.subject = commit.subject.replace(/\B@([a-z0-9](?:-?[a-z0-9/]){0,38})/g, (_, username) => {
            if (username.includes('/')) {
              return `@${username}`
            }

            return `[@${username}](${context.host}/${username})`
          })
        }
      }

      // remove references that already appear in the subject
      commit.references = commit.references.filter(reference => {
        if (issues.indexOf(reference.issue) === -1) {
          return true
        }

        return false
      })
      return commit
    },
    groupBy: 'type',
    commitGroupsSort: 'title',
    commitsSort: ['scope', 'subject'],
    noteGroupsSort: 'title',
    notesSort: compareFunc
  }
}

最后在 package.json 中的 scripts 添加一条语句

 "changelog": "conventional-changelog -p custom-config -i CHANGELOG.md -s -r 0  -n ./changelog-option.js"
//在这指定配置文件位置，本人放在了根目录，也可以指定其他地方
/*配置项说明：
-p custom-config 指定风格 
-i CHANGELOG.md 指定输出的文件名称
-s -r 0 指定增量更新，不会覆盖以前的更新日志
-n ./changelog-option.js 指定自定义配置
*/

注意：本项目中用到了 custom-config，因此需要先安装 custom-config【单纯的 changelog-option.js 是不完整的配置，在此只修改了自己需要的部分，其他部分默认】，如果不加这个插件，是不生效的。

npm i conventional-changelog-custom-config -D

最后再运行npm run changelog

总结

参考链接

参考链接：搞懂 ESLint 和 Prettier
参考链接：前端代码规范最佳实践：eslint+prettier+editorconfig+lint-staged
参考链接: settings.json是什么?对VS Code有什么用？