Vue3 项目配置 Git 提交规范（企业通用方案：husky + commitlint + cz-git + lint-staged）

作用说明

commitlint：校验 commit 信息，写的不规范直接阻止提交
husky ：git 钩子，拦截 git commit
cz-git ：交互式命令行，输入 pnpm cz 引导生成规范 commit（推荐团队使用）
lint-staged ：pre-commit 只对 git add 暂存文件执行 eslint / prettier，提交前自动修复代码

⚠️ 注意：husky v9 已经废弃 husky add 命令，下文原命令仅作参考；如果遇到 husky - add command is DEPRECATED，请使用文末替换方案手动创建钩子文件。 💻 跨系统说明：下面命令区分 Windows / Mac / Linux，解决不同操作系统执行钩子、文件编码问题。

1. 一次性安装全部依赖

pnpm（全系统通用）

javascript 复制代码

pnpm add -D husky @commitlint/cli @commitlint/config-conventional cz-git commitizen lint-staged

npm（全系统通用）

javascript 复制代码

npm i -D husky @commitlint/cli @commitlint/config-conventional cz-git commitizen lint-staged

2. 开启 husky（Mac / Linux / Windows PowerShell 都可以执行）

javascript 复制代码

# 初始化husky，生成 .husky 文件夹，自动在package.json添加prepare脚本
npx husky init

prepare ：别人 clone 项目后自动启用 husky，不管开发者是 Windows / Mac / Linux 系统，执行 npm install / pnpm install 自动安装 husky 钩子。

3. 创建 commit-msg 钩子（校验提交信息）

旧命令（husky < v8）

javascript 复制代码

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

Husky v9 手动创建（区分系统）

Mac / Linux 终端

javascript 复制代码

echo 'npx --no -- commitlint --edit $1' > .husky/commit-msg

Windows PowerShell

javascript 复制代码

'npx --no -- commitlint --edit $1' | Out-File .husky/commit-msg -Encoding utf8

4. pre-commit 钩子（提交前跑 eslint，只校验暂存文件）

旧命令（husky < v8）

javascript 复制代码

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

Husky v9 手动创建（区分系统）

Mac / Linux 终端

javascript 复制代码

echo 'npx lint-staged' > .husky/pre-commit

Windows PowerShell

javascript 复制代码

'npx lint-staged' | Out-File .husky/pre-commit -Encoding utf8

⚠️ Windows CMD 不推荐使用 > 写入文件，会产生编码乱码，优先用 PowerShell。

5. 根目录新建 commitlint.config.js（commit 校验规则）

javascript 复制代码

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // type 类型必须写，2=错误，always必须
    'type-enum': [
      2,
      'always',
      [
        'feat', // 新功能
        'fix', // bug修复
        'docs', // 文档
        'style', // 样式，不影响逻辑
        'refactor', // 重构
        'perf', // 性能优化
        'test', // 测试
        'build', // 构建打包
        'ci', // CI配置
        'chore', // 杂项，依赖/脚本
        'revert' // 回滚提交
      ]
    ],
    'subject-full-stop': [0, 'never'],
    'subject-case': [0, 'never'],
    'header-max-length': [2, 'always', 100]
  }
}

重要提醒 ：如果你的项目 package.json 设置了 "type":"module"（Vite Vue3 项目默认 ESM 模式），直接使用 module.exports 会报错 module is not defined in ES module scope。解决办法：将文件名改为 commitlint.config.cjs，无需修改内部代码。这个问题所有系统都会出现，不是 Windows 独有。

6. package.json 添加配置

javascript 复制代码

{
  "scripts": {
    "prepare": "husky install",
    "cz": "cz"
  },
  "config": {
    "commitizen": {
      "path": "node_modules/cz-git"
    }
  },
  "lint-staged": {
    "*.{js,ts,vue}": ["eslint --fix"],
    "*.{js,ts,vue,scss,css,md}": ["prettier --write"]
  }
}

跨系统命令差异：

pnpm：Mac / Windows / Linux 都支持简写 pnpm cz

npm：所有系统都不能简写，必须执行 npm run cz，不能写 npm cz。如果遇到 ESM 模块报错，可以修改 scripts 中 "cz": "git-cz" 提升全系统兼容性。

7. 两种提交方式（全系统通用）

方式 1：交互式提交（推荐团队，不容易写错）

javascript 复制代码

git add .
pnpm cz

回车后命令行一步步选择：type、scope、描述，自动生成规范 commit message。

方式 2：原生 git commit（会被 commitlint 校验）

✅ 正确格式：

javascript 复制代码

git commit -m "feat(router): 添加路由守卫"
git commit -m "fix: 修复sass变量不生效问题"

❌ 错误（直接阻止提交）：

javascript 复制代码

git commit -m "修改代码"

提交格式说明（约定式提交规范）

javascript 复制代码

<type>(<scope>): <subject>

type：上面枚举那 10 种
scope【可选】：改动范围，如 router、sass、layout、user
subject：简短描述，小写开头，不要句号

8. 配套 ESLint + Prettier（如果项目还没装，全系统通用）

javascript 复制代码

pnpm add -D eslint prettier eslint-plugin-vue eslint-config-prettier

lint-staged 在 pre-commit 阶段，会自动 fix 代码格式，无法修复的直接阻断 commit。

9. .gitignore 需要加入

javascript 复制代码

.husky/_

常用坑点（分系统）

Windows 系统 ：husky 钩子执行报错，原因多为文件编码，编辑器把 husky 下文件编码改成 UTF-8；同时关闭资源管理器「隐藏文件扩展名」 ，防止 commit-msg 被自动保存成 commit-msg.txt。Mac / Linux 一般不会出现后缀问题。
Mac / Linux 权限问题 ：少数情况 husky 钩子提示权限不足，执行 chmod +x .husky/* 给钩子文件增加执行权限。
临时跳过校验（不推荐，紧急 hotfix 才用，全系统通用）

javascript 复制代码

git commit --no-verify -m "xxx"

lint-staged 只会校验 git add 的文件，不会扫描全部代码，速度快，所有系统表现一致。
新同事 clone 项目，无论 Windows / Mac / Linux，执行 npm install / pnpm install 自动执行 prepare，husky 自动启用，无需额外操作。

极简版本（只校验 commit 信息，不需要代码格式化）

如果你不想 pre-commit 代码检查，只做 commit 消息校验：删掉 lint-staged 相关，删除 .husky/pre-commit 文件，只保留 commitlint 校验 commit 信息即可。

husky v9 废弃 husky add 的替代方案（跨系统总结）

v9 版本移除 husky add，手动创建钩子文件：

进入 .husky 文件夹，新建文件 commit-msg，写入：

javascript 复制代码

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

新建文件 pre-commit，写入：

javascript 复制代码

npx lint-staged

文件不要带 .txt后缀，Windows 最容易踩这个坑，Mac / Linux 一般不会自动追加后缀。