React 项目配置代码提交规范 ESLint、Pretttier、Husky、CommitLint

前言

团队开发的成员越来越多，项目都是由多个人进行开发和维护，每个人的代码书写习惯和风格又不尽相同，commit 的提交log 也是乱七八糟，为以后的开发和维护增添了很多困难，所以规范和约束在多人协作下，就显得尤为重要。

本文将以React 项目为例，在项目中配置 eslint + pretttier + husky + commitLint 代码提交规范

1、创建项目

npx create-react-app my-app --template typescript

完成之后如下图这个样子

2、配置 Eslint

2.1 安装依赖包

pnpm install eslint -D

2.2 安装成后 生成配置文件

// 按指示一路回车即可 
npx eslint --init 

2.3 配置.eslintrc.js, 直接用下方的eslintrc替换自动生成的即可，可避免很多坑

这里会出现一个 'module' is not defined报错所以在配置中加入 node: true

module.exports = {
  env: {
    browser: true,
    es2021: true,
    node: true, // 解决 'module' is not defined报错。
  },
  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: {},
};

2.4 使用eslint命令,在package的script中添加，fix表示可自动修复简单的问题。

"scripts": {
   "lint": "eslint --fix \"./src/**/*.{js,jsx,ts,tsx}\""
}

OK,到这里，我们可以先来测试一下，写一行未使用的代码，执行 npm run lint，然后就可以看到如下报错，提示userName 未引用

2.5 设置忽略文件 .eslintignore

dist/*
node_modules/*
*.json
public

3、配置 prettier 格式化代码

3.1 安装依赖装包

pnpm install prettier -D

3.2 安装 Prettier - Code formatter 插件

3.3 配置.prettierrc.js文件

重启 vscode 后，我们在 .prettierrc.js 文件中配置的代码风格才会生效

module.exports = {
  // 一行的字符数，如果超过会进行换行，默认为80
  printWidth: 100,
  // 行位是否使用分号，默认为true
  semi: true,
  // 字符串是否使用单引号，默认为false，使用双引号
  singleQuote: true,
  // 一个tab代表几个空格数，默认为2
  tabWidth: 2,
  // 是否使用尾逗号，有三个可选值"<none|es5|all>"
  trailingComma: "none",
};

在 packages.json 中的 script 配置命令

  "scripts": {
    "format": "prettier --write \"src/**/*.+(js|ts|jsx|tsx)\"",
  }

运行该命令，会将我们项目中的文件都格式化一遍，后续如果添加其他格式的文件，可在该命令中添加，例如：.less后缀的文件

3.4、设置 .prettierignore 忽略文件

node_modules/**
dist/**
public/**
doc/**

3.5、解决ESLint与Prettier的冲突

ESLint

• 目的：ESLint 主要用于发现代码中的问题，如潜在的错误、不一致的编码风格、未使用的变量等。
• 可配置性：ESLint 允许自定义规则，使其可以强制实施特定的编码标准和最佳实践。

Prettier

• 目的：Prettier 主要用于自动格式化代码，以保持代码风格的一致性。
• 风格规则：Prettier 有一套默认的风格规则，例如缩进、行宽、引号等，并且这些规则不太可配置。

冲突原因

• 冲突通常发生在两个工具对某些代码风格规则有不同的处理方式。例如，ESLint 可能要求使用单引号，而 Prettier 默认使用双引号。
• 当这两个工具同时运行时，它们可能会对代码的同一部分提出不同的修改建议，从而造成冲突。

安装依赖包

pnpm install eslint-config-prettier eslint-plugin-prettier -D

eslint-config-prettier 基于 prettier 代码风格的 eslint 规则，即eslint使用pretter规则来格式化代码。

eslint-plugin-prettier 禁用所有与格式相关的 eslint 规则，解决 prettier 与 eslint 规则冲突，确保将其放在 extends 队列最后，这样它将覆盖其他配置

3.6 增加 .vscode 配置 settings.json 自动完成格式化

// settings.json
{
  // 保存的时候自动格式化
  "editor.formatOnSave": true,
  // 默认格式化工具选择prettier
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

配置完成之后，我们保存代码的时候就可以自动完格式化了

4、配置 husky

4.1、安装并初始化husky

// 初始化husky。 
// 1将prepare脚本添加到package 
// 2、根目录创建.husky文件夹，包含pre-commit钩子
pnpm install husky -D

npx husky-init

4.2 安装并配置lint-staged

只检查通过git add添加到暂存区的文件，避免每次检查都把整个项目的代码都检查一遍，从而提高效率

pnpm install lint-staged -D

4.3 配置packages.json 命令

// 设置lint-staged；提交时prettier代码格式化，eslint检查修复
{
  "lint-staged": {
    "**/*.{js,jsx,ts,tsx}": "npm run lint",
    "**/*.{js,jsx,tsx,ts,less,md,json}": [
      "prettier --write",
      "eslint --fix"
    ]
  },
}

4.4 修改.husky/pre-commit文件，使提交时能执行lint-staged钩子

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

pnpm exec lint-staged

// 删除npm test

5、 配置 commit-msg

commitlint 检查提交消息是否符合常规提交格式，用于在每次提交时生成符合规范的commit消息。

5.1 安装commit-msg

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

5.2 添加 commitlint.config.js 配置文件

module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    // type 类型定义
    "type-enum": [
      2,
      "always",
      [
        "feat", // 新功能 feature
        "fix", // 修复 bug
        "docs", // 文档注释
        "style", // 代码格式(不影响代码运行的变动)
        "refactor", // 重构(既不增加新功能，也不是修复bug)
        "perf", // 性能优化
        "test", // 增加测试
        "chore", // 构建过程或辅助工具的变动
        "revert", // 回退
        "build", // 打包
      ],
    ],
    // subject 大小写不做校验
    // 自动部署的BUILD ROBOT的commit信息大写，以作区别
    "subject-case": [0],
  },
};

@commitlint/config-conventional 这是一个规范配置,标识采用什么规范来执行消息校验, 这个默认是Angular的提交规范

类型	描述
build	编译相关的修改，例如发布版本、对项目构建或者依赖的改动
chore	其他修改, 比如改变构建流程、或者增加依赖库、工具等
docs	文档修改
ci	持续集成修改
feat	新特性、新功能
fix	bug修复
perf	优化相关，比如提升性能、体验
refactor	代码重构
revert	回滚上一个版本
style	代码格式修改, 注意不是 css 修改
test	测试用例修改｜

5.3 执行以下命令添加commitlint钩子

npx husky add .husky/commit-msg "npm run commitlint"

5.4 在packages.json 配置

 "scripts": {
    "commitlint": "commitlint --config commitlint.config.js -e -V"
  },

按上面步骤修改完，我们在提交代码时候，如果随便写一个提交message将会报错，不允许提交，如下所示：

试试提交代码

5.5 正常提交

git commit -m 'feat: 测试一下'

6、自定义代码提交规则

自定义提交规则可以根据团队开发规范来进行额外配置，目前我所在的团队提交规则是，会把每个需求的产品文档链接关联到每一个feature，这样后续要是有问题，也方便找到对应的产品文档.

配置如下

主要就增加了plugin 和 三个rule 规则

'must-add-document-url": [2, "always"]', // 加入自定义规则
'body-max-line-length': [2, 'always', 200], // body最大内容行数
'header-max-length': [2, 'always', 200], // header 最大长度

module.exports = {
 extends: ["@commitlint/config-conventional"],
 rules: {
   // type 类型定义
   "type-enum": [
     2,
     "always",
     [
       "feat", // 新功能、新特性feature
       "fix", // 修复 bug
       "docs", // 文档修改
       "style", // 代码格式(不影响代码运行的变动)
       "refactor", // 代码重构
       "perf", // 优化相关，比如提升性能、体验
       "test", // 测试用例修改
       "chore", // 其他修改, 比如改变构建流程、或者增加依赖库、工具等
       "revert", // 回滚上一个版本
       "build", // 编译相关的修改，例如发布版本、对项目构建或者依赖的改动
     ],
   ],
   // subject 大小写不做校验
   // 自动部署的BUILD ROBOT的commit信息大写，以作区别
   "subject-case": [0],
   "must-add-document-url": [2, "always"], // 加入自定义规则
   'body-max-line-length': [2, 'always', 200], // 加入自定义规则
   'header-max-length': [2, 'always', 200], // 加入自定义规则
 },
 plugins: [
   {
     rules: {
       "must-add-document-url": ({ type, body }) => {
         const ALIYUN_DOCUMENT_PREFIX = "https://devops.aliyun.com";

         // 排除的类型
         const excludeTypes = ["chore", "refactor", "style", "test"];
         if (excludeTypes.includes(type)) {
           return [true];
         }

         return [
           body && body.includes(ALIYUN_DOCUMENT_PREFIX),
           `提交的内容中必须包含云效相关文档地址`,
         ];
       },
     },
   },
 ],
};

然后再来测试一下

git commit -m "feat: 测试自定义提交规则"，然后就提示需要云效的文档链接

正确提交

feat: 测试自定义提交规则 ｜

https://devops.aliyun.com/xxxxxx

正常提交上来了

7、总结

本文从实战出发，为一个React 项目添加了eslint + prettier + husky + lint-staged项目规范以保证项目的质量、统一格式、风格。希望大家能从中学到知识。代码已经上传到github上, 点击这里即可查看。

如果你觉得本文对你有些许帮助的话，记得点个赞哦👍！🌹

参考文章

# 代码提交规范-ESLint+Prettier+husky+Commitlint

commitlint 从0到1 (git commit 校验工具)