shared-tooling-git-hooks

Git 钩子

**快速指南：**使用 Husky v9 管理 Git 钩子，并在 package.json 中设置 "prepare": "husky"（不要使用 "husky install"）。使用 lint-staged v16 仅检查暂存文件。使用 commitlint 验证符合 Conventional Commits 规范的提交消息。提交前钩子应在 10 秒内完成。在 CI/生产环境中设置 HUSKY=0。

---

<critical_requirements>

关键要求：使用此技能前

所有代码都必须遵循项目在 CLAUDE.md 中的约定（kebab-case、具名导出、导入顺序、import type、具名常量）

（必须在 package.json 中使用 "prepare": "husky"，不要使用已弃用的 "husky install"）

（必须通过 lint-staged 仅检查暂存文件——提交前绝不能检查整个代码库）

（必须在 CI/生产环境中设置 HUSKY=0，以禁用钩子）

（必须在 .husky/ 目录中使用普通钩子文件——Husky v9 中不能使用 shebang 行，也不能加载 husky.sh）

（提交前钩子必须在 10 秒内完成——将耗时任务移至推送前或 CI）

</critical_requirements>

---

**自动检测：**Husky、husky init、.husky/、提交前钩子、lint-staged、commitlint、Conventional Commits、commit-msg 钩子、Git 钩子、prepare 脚本

适用场景：

• 使用 Husky + lint-staged 设置提交前钩子
• 使用 commitlint 配置提交消息验证
• 从 Husky v8 迁移到 v9
• 在单体仓库中配置 Git 钩子
• 在 CI/生产环境中禁用钩子

不适用场景：

• 配置 Linter/格式化工具本身（属于其他事项）
• 配置 CI/CD 管道（属于其他事项）
• 运行时应用代码（此工具仅用于开发者工作流）

涵盖的关键模式：

• Husky v9 设置与钩子创建
• lint-staged v16 配置模式
• 使用 commitlint 与 Conventional Commits
• 在 CI/生产环境中禁用钩子
• 单体仓库设置
• 从 Husky v8 迁移到 v9

详细资源：

• examples/core.md - 设置、lint-staged 配置、commitlint、CI 处理、单体仓库、迁移
• reference.md - 决策框架、工具比较、反模式

---

理念

Git 钩子是一种开发者工作流工具——它能及早发现问题，同时保持快速且不阻塞。目标是仅对暂存文件提供快速反馈（< 10 秒）。钩子属于可选基础设施；许多项目即使不使用钩子也能正常运行。

适用场景：

• 代码质量门禁有助于避免 CI 失败的团队项目
• 已建立 Lint/格式化规范且需要强制执行的项目
• 希望在代码进入 CI 前获得快速反馈
• 运行完整 Lint 耗时过长的单体仓库

不适用场景：

• 总会记得运行 Lint 的个人项目（增加开销，却没有收益）
• 尚未建立 Lint/格式化规范的项目（先设置 Lint）
• 提交前钩子耗时超过 10 秒的情况（改由 CI 处理）
• 钩子会增加阻力却没有收益的纯 CI 项目

---

核心模式

模式 1：设置 Husky v9

Husky v9 在 .husky/ 目录中使用普通 Shell 脚本。不需要 shebang 行。prepare 脚本会自动为所有团队成员安装钩子。

# Full setup in 4 commands
bun add -D husky
bunx husky init       # Creates .husky/ and adds "prepare": "husky" to package.json
bun add -D lint-staged
echo "bunx lint-staged" > .husky/pre-commit

要点：

• "prepare": "husky"（不要使用 "husky install"——该命令已弃用，并会在 v10 中失效）
• 钩子文件是普通 Shell 脚本（v9 中不需要 shebang）
• HUSKY=0 可禁用钩子（CI/生产环境）；HUSKY=2 可启用调试模式
• v9.1.1+ 支持直接运行包命令，无需使用 npx/bunx

完整设置和 package.json 配置请参阅 examples/core.md。

---

模式 2：使用 lint-staged 的提交前钩子

lint-staged v16 仅对暂存文件运行命令。使用 picomatch 进行 glob 匹配（替代了 micromatch）。

// lint-staged.config.mjs
export default {
  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{css,scss}": ["prettier --write"],
};

类型检查需要使用函数语法（会对所有文件运行，而不只是暂存文件）：

// lint-staged.config.mjs — with type checking
export default {
  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{ts,tsx,js,jsx}": () => "tsc --noEmit",
};

优点： 仅处理暂存文件，自动修复可减少手动工作，反馈迅速

v16 破坏性变更： 已移除 --shell 标志（改用 shell 脚本），需要 Node.js 20.18+

多个文件类型模式和 v16 迁移详情，请参阅 examples/core.md。

---

模式 3：使用 Conventional Commits 的 Commitlint

commitlint v20+ 会验证提交消息。原生支持 ESM——使用 .mjs 配置扩展名。

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

# .husky/commit-msg
bunx commitlint --edit $1

// commitlint.config.mjs (MUST be .mjs for Node v24 compatibility)
export default {
  extends: ["@commitlint/config-conventional"],
};

格式：type(scope): description——类型：feat、fix、docs、refactor、test、chore 等。

v20 变更和高级配置，请参阅 examples/core.md。

---

模式 4：CI/生产环境处理

在不应运行钩子的环境中禁用 Husky。

# CI pipelines
HUSKY=0 npm install

# GitHub Actions
env:
  HUSKY: 0

原因： 防止生产环境未安装 devDependencies 时钩子安装失败。

条件式 prepare 脚本的替代方案，请参阅 examples/core.md。

---

模式 5：单体仓库设置

适用于 package.json 不在仓库根目录的单体仓库。

// apps/frontend/package.json
{
  "scripts": {
    "prepare": "cd ../.. && husky apps/frontend/.husky"
  }
}

要点： 先导航到仓库根目录，再将 .husky/ 目录路径传递给 Husky。

---

模式 6：从 Husky v8 迁移到 v9

分步操作：更新 prepare 脚本，从钩子文件中移除 shebang 和 husky.sh 引用，删除 .husky/.gitignore，如果使用了 pinst，则将其移除。

重要： 使用已弃用的 shebang #!/usr/bin/env sh 并引用 husky.sh 的钩子将在 v10.0.0 中失效。请立即迁移。

完整迁移指南，请参阅 examples/core.md。

---

<decision_framework>

决策框架

提交前运行什么

What to run pre-commit?
├─ Fast (< 10 seconds)?
│   ├─ Lint with auto-fix → YES (lint-staged)
│   ├─ Format → YES (lint-staged)
│   └─ Type check (--noEmit) → YES (lint-staged)
└─ Slow (> 10 seconds)?
    ├─ Full test suite → NO (pre-push or CI)
    ├─ Full build → NO (CI)
    └─ E2E tests → NO (CI)

哪种任务使用哪种钩子

Which Git hook?
├─ Before committing? → pre-commit (lint-staged)
├─ Validating commit message? → commit-msg (commitlint)
├─ Before pushing? → pre-push (type check, unit tests)
├─ Before merging? → pre-merge-commit (v9.1.5+)
└─ After checkout/merge? → post-checkout / post-merge (install deps)

提交前运行时机指南

任务	耗时	提交前运行？
lint-staged（仅暂存文件）	< 5s	是
代码格式化	< 2s	是
类型检查（--noEmit）	< 10s	是
完整测试套件	> 30s	否（CI）
E2E 测试	> 60s	否（CI）
完整构建	> 30s	否（CI）

Husky 与替代方案的比较，请参阅 reference.md。

</decision_framework>

---

<red_flags>

危险信号

高优先级问题：

• 使用已弃用的 "prepare": "husky install"，而非 "prepare": "husky"（将在 v10 中失效）
• 在 pre-commit 钩子中对整个代码库运行完整 lint（速度太慢，也违背了仅检查暂存文件的目的）
• 在 package.json 中使用 v4 风格的 "husky": { "hooks": {} } 配置（v9 不支持）
• 使用 HUSKY_GIT_PARAMS 环境变量（已弃用，请改用 $1）

中优先级问题：

• pre-commit 钩子耗时超过 10 秒（容易导致滥用 --no-verify）
• 在 CI/生产环境中未设置 HUSKY=0（未安装 devDependencies 时钩子可能失败）
• 在钩子文件中使用已弃用的 shebang #!/usr/bin/env sh 并引用 husky.sh（将在 v10 中失效）
• 在 Node v24 上使用 .js 扩展名的 commitlint 配置（请改用 .mjs）

注意事项和边缘情况：

• git commit --no-verify 会完全跳过钩子——这是紧急逃生口，不应常规使用
• lint-staged 函数语法 () => "tsc --noEmit" 会对所有文件运行，而不只是暂存文件
• 钩子文件名必须与 Git 的准确名称一致（pre-commit、commit-msg）——不能带扩展名，且区分大小写
• HUSKY=2 会启用调试模式（取代已弃用的 HUSKY_DEBUG=1）
• commitlint v20+ 原生支持 ESM——使用 .mjs 配置扩展名可避免模块加载问题
• Windows 用户需要在 commit-msg 钩子中转义 $1
• 在单体仓库中，prepare 脚本必须先切换到仓库根目录，再运行 husky
• ~/.huskyrc 支持将在 v10 中移除——请迁移到 .config/husky/init.sh
• lint-staged v16 使用 picomatch（而非 micromatch）——glob 模式可能略有不同

</red_flags>

---

<critical_reminders>

重要提醒

所有代码都必须遵循 CLAUDE.md 中的项目约定

（必须在 package.json 中使用 "prepare": "husky"——不能使用已弃用的 "husky install"）

（必须仅通过 lint-staged 检查暂存文件——绝不能在 pre-commit 中检查整个代码库）

（必须在 CI/生产环境中设置 HUSKY=0，以禁用钩子）

（必须在 .husky/ 目录中使用纯钩子文件——v9 中不能添加 shebang 行，也不能引用 husky.sh）

（必须将 pre-commit 钩子的耗时控制在 10 秒以内——将耗时较长的任务移到 pre-push 或 CI）

不遵守这些规则会导致提交缓慢、CI 构建失败，以及将在 Husky v10 中失效的弃用钩子模式。

</critical_reminders>