前端项目规范配置（husky、eslint、stylelint、lint-staged、commitlint）

前言

按照本文的步骤，你可以在你的现有项目中快速地加入 husky、eslint、stylelint、lint-staged、commitlint一系列代码校验工具，保证代码风格一致性，为编写高质量代码打下坚实的基础。

一、Eslint

安装

pnpm install eslint --save-dev 

添加或修改.eslintrc.js文件

module.exports = {
  root: true, // 声明这是根配置文件，不再向上查找
  env: { browser: true, es2023: true },
  // 使用的规则集，可以是一个字符串（预设）或自定义规则的对象
  extends: 'eslint:recommended',
  // plugins 可以提供额外的规则配置，如vue，这些规则需要在 rules 中进行配置。
  plugins: ['vue'],
  // 自定义规则
  rules: {
    'no-console': 'off', // 允许使用console
    'indent': ['error', 2], // 两个空格的缩进
    // 更多规则...
  },
  // 默认使用espree，可以选择其他解析器，例如使用ts
  parser: "@typescript-eslint/parser",
  parserOptions: {
    "parser": "@typescript-eslint/parser",
    "sourceType": "module",
    "project": "./tsconfig.json" // 指定tsconfig.json文件路径
  },
  //定义全局变量
  globals: {
    "wx": "readonly"
  },
  // 配置哪些文件或目录应该被 ESLint 忽略
  ignorePatterns: ["node_modules/", "build/", "dist/"]
}

以上配置可以根据自己需要来自由修改，规则集推荐使用 eslint-config-mature ，该规范包集eslint、stylelint、prettier规范于一身，集各大厂百家之长，免去安装各种包的繁杂操作，用起来很方便。

pnpm install eslint-config-mature eslint-plugin-import --save-dev

eslint 和 prettier 两者可以配合使用，即 使用 prettier 做格式化， eslint 做代码校验。

pnpm install prettier eslint-plugin-prettier --save-dev

更新.eslintrc.js文件

module.exports = {
  // 使用的规则集，可以是一个字符串（预设）或自定义规则的对象，优先级由低到高
  extends: [
    'plugin:react/recommended', // 优先你的react或者Vue规则，优先级最低
    'eslint-config-mature/prettier', // 主要用于格式化模板，优先级应更低
    'eslint-config-mature',
    'eslint-config-mature/ts', // 如果使用ts
  ],
}

二、Stylelint

安装相关包，如果使用 scss 的话需要额外安装 stylelint-scss postcss-scss

pnpm install stylelint stylelint-scss postcss-scss stylelint-config-recess-order --save-dev

stylelintrc.js 配置

module.exports = {
  extends: [
    'stylelint-config-recess-order', // 属性排序
    'eslint-config-mature/stylelint/style', // 使用 eslint-config-mature 包的规则
    'eslint-config-mature/stylelint/style-scss',
  ],
  ignoreFiles: [
    '**/*.js',
    '**/*.cjs',
    '**/*.jsx',
    '**/*.tsx',
    '**/*.ts',
    "node_modules/",
    "dist/",
    "public/",
    "docs/",
  ],
  overrides: [
    {
      files: ["**/*.scss"],
      customSyntax: "postcss-scss", // 处理.scss文件时使用postcss-scss语法解析器
    },
  ],
  rules: {
    // 自定义覆盖规则
  },
};

手动lint

package.json 的 scripts 里添加

  "lint": "yarn lint:eslint && yarn lint:stylelint",
    "lint:eslint": "eslint -c .eslintrc.cjs --ext .ts,.tsx,.js src --fix --report-unused-disable-directives --max-warnings 0",
    "lint:stylelint": "stylelint src/**/*.{html,css,scss} --fix --max-warnings 0",

运行 npm run lint 即可进行代码检查，–fix 去掉 则关闭自动修复问题。
推荐安装 eslint 和 stylelint 的 vscode 插件，可以实时提示并支持保存自动修复等功能。

三、husky

每次手动去运行命令检查太麻烦了，而且也很考验小伙伴的自觉性。
husky 是一个 Git 钩子（Git hooks）工具，它可以让你在 Git 事件发生时执行脚本，进行代码格式化、测试等操作

常见的钩子

pre-commit：在执行 Git commit 命令之前触发，用于在提交代码前进行代码检查、格式化、测试等操作。
commit-msg：在提交消息（commit message）被创建后，但提交操作尚未完成之前触发，用于校验提交消息的格式和内容。
pre-push：在执行 Git push 命令之前触发，用于在推送代码前进行额外检查、测试等操作。

具体的使用步骤如下：

1. 安装 husky

pnpm add  husky --save-dev

2. 启用git 钩子 输入以下命令

pnpm pkg set scripts.prepare="husky install"

安装成功后会在 package.json 文件中 script 中生成命令

注: 如未自动生成需手动添加，将以下内容粘贴到 package.json 文件中

// package.json
{
  "scripts": {
    "prepare": "husky install"
  }
}

3. 执行如下代码，创建.husky目录，

pnpm run prepare

执行成功后，项目中会生成一个 .husky 目录

4. 添加命令到pre-commit 钩子
   给 pre-commit 钩子添加 npx lint-staged 命令

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

四、lint-staged

lint-staged 可以让你在 Git 暂存（staged）区域中的文件上运行脚本，通常用于在提交前对代码进行格式化、静态检查等操作。
可以在项目中使用 lint-staged 配合 husky 钩子来执行针对暂存文件的脚本。

1. 安装

pnpm add lint-staged --save-dev

在 package.json 文件中添加以下配置：

"lint-staged": {
    "src/**/*.{js,jsx,ts,tsx}": [
      "eslint --max-warnings 0"
    ],
    "src/**/*.{vue,less,postcss,css,scss}": [
      "stylelint --max-warnings 0"
    ]
  }

src/**/*.{js,ts,vue,tsx}为校验暂存区、指定目录下的文件类型，可以根据自己需要配置。
现在，在代码提交时就会自动执行 npx lint-staged 命令校验代码。

注意： 没有 --fix 参数，某些场景下自动修复会导致代码莫名其妙的bug，如果自动修复了你可能都不知道就合了。

五、Commitizen 交互式提交

Commitizen 是一个用于规范化提交信息的工具，它能够帮助项目团队创建一致、易读的 Git 提交消息。通过使用 Commitizen，你可以确保提交信息按照预定义的规范格式化，方便后续查看和管理项目历史记录。

1. 安装
   运行以下命令，安装 Commitizen 和 Commitizen 适配器，比如 cz-conventional-changelog：

pnpm add commitizen cz-conventional-changelog -D 

2. 安装完成后，在 package.json 中添加一个 config.commitizen 的字段，并设置它的值为 cz-conventional-changelog。

"config": {
  "commitizen": {
    "path": "cz-conventional-changelog"
  }
}

3. 在 package.json 中的 scripts 字段中添加一个 commit 的命令。 示例如下：

"scripts": {
  "commit": "git-cz"
}

4. 执行 npm run commit 就可以进行交互式提交了。

六、commitlint

Commitizen是用来创建规范化提交的，如果项目成员没有使用 npm run commit 来提交，而是直接使用 git commit 的话还是有可能生成不规范提交的，所以还需要对最终的提交格式做一下校验，接下来添加提交格式校验

1. 安装：

pnpm add commitlint @commitlint/config-conventional -D

2. 添加 commit-msg 钩子

npx husky add .husky/commit-msg "npx commitlint --config .commitlintrc.cjs --color --edit "$1""

如果你全局安装commitlint的话，可以不使用 npx 命令

4. 创建配置文件 .commitlintrc.cjs

/**
  feat:新增功能
  fix:修复bug
  docs:文档更新
  style: 代码格式修改
  refactor: 重构代码
  test: 测试用例修改
  build: 构建系统或包依赖修改
  ci: CI/CD 配置修改
  chore: 其他杂项修改
  revert: 回滚到上一版本
  perf: 性能优化
 */

module.exports = {
  // 使用 @commitlint/config-conventional规则
  extends: ['@commitlint/config-conventional'],
  // 'rule': [0:disable|1:warn|2:error, 'always|never', ruleValue]
  // 定义验证规则
  rules: {

    // header最大94字符
    'header-max-length': [0, 'always', 94],

    // subject不能为空
    'subject-empty': [2, 'never'],

    // type的类型必须在指定范围内
    'type-enum': [
      2,
      'always',
      ['build', 'ci', 'chore', 'docs', 'feat', 'fix', 'perf', 'refactor', 'revert', 'style', 'test']
    ],

    // type不能为空
    "type-empty": [2, 'never'],

    // type必须小写
    "type-case": [2, "always", 'lowerCase'],

    // scope 允许为空
    "scope-empty": [0, "never"],

    // scope 必须小写
    "scope-case": [2, "always", "lowerCase"],

    // scope 不限制类型
    "scope-enum": [2, "always", []]
  }
};

一般建议保持 scope 强制和小写校验,但允许为空。这样可以鼓励使用 scope 来细分提交分类,但不强制要求。给予一定灵活性。
当 scope 非必填时,可以在提交时按需要填写,比如:

feat(home): add new parser
feat: add new feature

第一条指定了 scope,第二条未指定也能通过校验。

以上只是最基础的配置，可以根据团队实际情况自行更改，例如在提交信息时带上需求/Bug编号等。

补充: 另外提交类型中的 style 是一个通用的概念：
commit message 中的style表示的是不影响代码逻辑的修改,比如:

• 代码空格
• 格式化
• 缺失分号
• 代码注释

等与程序逻辑无关的修改。
另外一些文档也将style解释为代码风格的修改。
所以更准确的理解是"风格修改",而不是具体指CSS。
相比之下,如果是修改CSS样式表,建议使用下面两种类型:

• feat:新增样式特性
• fix:修复样式问题

如果修改的只是空格、格式化等与逻辑无关的变化,才使用style类型。当然,style也可以具体表示CSS修改,需要看团队自己的约定。

七、其他自定义校验

除了使用一些现成的npm包外，我们也可以自己写一些规则， husky 提供了钩子，我们在钩子里添加要执行的逻辑即可。

1.自定义 husky 校验-校验分支名

在校验代码格式之前，我们还想先看一下分支名是否符合要求，而不是让大家可以随心所欲，团队合作的项目尤其推荐哦。
假设我们要求的分支名格式为 feat_name_summary
在.husky 目录下新建目录custom，加入文件 branch-check.sh，文件内容为：

// .husky/custom/branch-check.sh

#!/bin/bash

# 获取当前所在的 Git 分支名
branch_name=$(git symbolic-ref --short HEAD)

# 分支名规则
pattern="^(fix|feat)_[a-z]{2,}_([a-zA-Z0-9]+)$"

# 正则不匹配就错误提示
if [[ ! $branch_name =~ $pattern ]]; then
  echo "Error: Invalid branch name. Branch name must match '(fix|feat)_(名字缩写如lyl等)_(具体改动如addcoupon)' format."
  exit 1
fi

分支名规则根据实际情况自行修改。
然后在pre-commit中加入这个脚本，在校验代码之前

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

# 校验分支
. "$(dirname -- "$0")/custom/branch-check.sh"

# 校验代码
npx lint-staged

完成后，以后再提交时就会校验一下分支是否符合规范。

2.自定义 husky 校验-校验文件注释

为了项目更好的可读性和可维护性，在文件开头写一下注释，告诉别人这个文件是干嘛的是很有必要的，减少小伙伴的阅读和维护成本。
看下效果：

/**
 * @description 封装表单相关行为
 */

// balabala

当然，还有自动生成文件注释的插件，还会额外带上什么 author、updateTime 之类的大家感兴趣可以自己研究。
那具体怎么搞？
依旧在 .husky 下新建文件 custom/desc-check.sh ，注意，我们只校验src目录下的文件

#!/bin/bash

# 获取 git 暂存区中 src 目录下所有 js、ts 和 tsx 文件（不包括 .d.ts 文件）
files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^src/.*\.(js|ts|tsx)$' || true | grep -vE '\.d\.ts$' || true)


# 遍历文件列表
for file in $files; do
  # 检查文件的前 10 行中是否包含针对整个文件的 @description 注释
  if ! head -n 10 "$file" | awk '/\/\*\*/,/\*\//{if(/@description/){found=1;exit}}END{exit !found}'; then
    # 如果不存在，则输出错误信息并退出脚本
    echo "Error: $file 必须在文件开头包含指定的jsdoc注释属性 @description xxx"
    exit 1
  fi
done

然后在pre-commit中加入这个脚本，在校验代码之前

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

# 校验分支
. "$(dirname -- "$0")/custom/branch-check.sh"

# 校验文件注释
. "$(dirname -- "$0")/custom/desc-check.sh"

# 校验代码
npx lint-staged

大家还可以自己尝试编写其他校验。