使用 Husky + Commitlint + Lint-staged 约束每一次 Git 提交

---

前端工程化配置指南

当一个项目有多个参与者，此时保持统一的风格和规范有利于项目的维护

常见工具说明 🎉

• Eslint ESLint静态分析您的代码以快速查找并修复JavaScript代码中的问题
• prettier 代码格式化工具，更好的代码风格效果
• husky Git hooks 工具, 可以在执行 git 命令时，执行自定义的脚本程序
• lint-staged 对暂存区 (git add) 文件执行脚本
• commitlint 检测 git commit 内容是否符合定义的规范

eslint和prettier这个2个工具不会直接约束git提交，这里就不在过多描述了

一、Husky

Husky 是一款 Git Hooks 工具，可以在执行特定的 git 命令时（如: git commit, git push）触发对应的脚本，您可以使用它来检查提交消息、运行测试、检查代码等。

提示

Git Hooks 简单来说就是git执行某些操作时而触发定义的动作（钩子）

安装

具体安装请查看官网安装指导

npm

npx husky-init && npm install

pnpm

pnpm dlx husky-init && pnpm install

yarn

yarn dlx husky-init --yarn2 && yarn

安装完成后，你会发现发生以下变化：

1. 项目根目录出现 .husky文件夹
2. .husky文件夹里面有一个名为pre-commit脚本文件

# .husky/pre-commit

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

npm test

pre-commit 见名知义，就是在 commit 执行前的脚本文件。 pre-commit 文件中默认配置 npm test，此时执行git commit操作会自动执行npm test。

3.package.json增加了一个 prepare脚本

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

prepare脚本会在每次npm install（不带参数）之后自动执行。 也就是说当我们执行npm install安装完项目依赖后会执行 husky install命令，该命令会创建.husky/目录并指定该目录为git hooks所在的目录。

创建新的钩子

npx husky add .husky/pre-commit "npm test"

提示

如果面临特殊情况，需要绕过 Git Hooks，可以使用 --no-verify

git commit -m "commit_message" --no-verify

二、lint-staged

在提交的代码的时候，可以通过 ESLint、Prettier 等工具来格式化代码

但如果直接处理全部代码，首先是可能存在性能问题，其次是可能会修改掉别的同事的代码

这时可以引入 lint-staged，它可以过滤出 Git 代码暂存区文件，这样就不会影响到未更改的文件

安装和设置

安装 lint-staged

npm

npm add -D lint-staged

pnpm

pnpm add -D lint-staged

yarn

yarn add -D lint-staged

在 package.json 配置lint-staged所需要的规则

{
  "lint-staged": {
    "*.{js,ts}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{cjs,json}": [
      "prettier --write"
    ],
    "*.{vue,html}": [
      "eslint --fix",
      "prettier --write",
      "stylelint --fix"
    ],
    "*.{scss,css}": [
      "stylelint --fix",
      "prettier --write"
    ],
    "*.md": [
      "prettier --write"
    ]
  }
}

设置pre-commitgit hook 来运行lint-staged

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

然后 .husky文件夹里出现名为pre-commit脚本文件

# .husky/pre-commit

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

npx lint-staged

三、Commitlint

Commitlint 可以校验 git commit message, 只有规范的 commit message 才能提交，

简单来说，就是当我们运行git commmit -m 'xxx'时，来检查'xxx'是不是满足团队约定好的提交规范的工具。

安装

• @commitlint/cli 是脚手架工具
• @commitlint/config-conventional 是官方推荐可继承的配置文件

npm install -g @commitlint/cli @commitlint/config-conventional

这里是默认安装全局，当然你也可以安装在项目里

npm

npm add -D @commitlint/cli @commitlint/config-conventional

pnpm

pnpm add -D @commitlint/cli @commitlint/config-conventional

yarn

yarn add -D @commitlint/cli @commitlint/config-conventional

项目根目录新建一个 commitlint.config.js 文件

echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

commitlint.config.js 文件配置继承 @commitlint/config-conventional，当然你也是可以自定义规则

// commitlint.config.js
module.exports = {
    // 继承的规则
    extends: ["@commitlint/config-conventional"],
    // 自定义规则
    rules: {
        // @see https://commitlint.js.org/#/reference-rules

        // 提交类型枚举，git提交type必须是以下类型
        "type-enum": [
            2,
            "always",
            [
                "feat", // 新增功能
                "fix", // 修复缺陷
                "docs", // 文档变更
                "style", // 代码格式（不影响功能，例如空格、分号等格式修正）
                "refactor", // 代码重构（不包括 bug 修复、功能新增）
                "perf", // 性能优化
                "test", // 添加疏漏测试或已有测试改动
                "build", // 构建流程、外部依赖变更（如升级 npm 包、修改 webpack 配置等）
                "ci", // 修改 CI 配置、脚本
                "revert", // 回滚 commit
                "chore", // 对构建过程或辅助工具和库的更改（不影响源文件、测试用例）
            ],
        ],
        "subject-case": [0], // subject大小写不做校验
    },
}

新增 Husky hook

添加 commit-msg 脚本，这样在每次 git commit 的时候执行 commitlint 校验

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

脚本文件内容如下

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

npx --no-install commitlint --edit $1

完成以上配置之后，只有满足规范的 commit message 才能提交

参考

• 使用 Husky + Commitlint + Lint-staged 约束每一次 Git 提交
• Eslint + Prettier + Husky + Commitlint+ Lint-staged 规范前端工程代码规范