husky 切换 simlple-git-hook 失效解决方法

husky 切换 simple-git-hook 失效解决方法

1. Git Hook 工作原理

Git Hook 是 Git 提供的自动化脚本机制，允许开发者在特定 Git 事件（如提交、推送）前后触发自定义脚本。所有钩子脚本默认存储在 .git/hooks 目录下，文件名对应事件名称（如 pre-commit、commit-msg 等）。当 Git 操作触发事件时，系统会执行对应的脚本：

• 成功条件 ：脚本执行后返回 0 状态码，则流程继续。
• 失败条件 ：返回非 0 状态码，则流程中断。

由于 .git/hooks 目录下的文件不纳入版本控制，直接修改存在协作和维护问题，因此诞生了 Git Hook 管理工具（如 husky、simple-git-hook）。

---

2. Husky 工作原理

Husky 是一个流行的 Git Hook 管理工具，通过 劫持 .git/hooks 目录 实现配置集中化管理。具体流程：

1. 安装时 ：Husky 在 .git/hooks 中生成通用脚本，指向其内部逻辑。
2. 配置方式 ：在 package.json 或 .husky 目录中定义 Hook 逻辑（如 pre-commit: npm run lint）。
3. 触发流程 ：
   • Git 事件触发 → 调用 .git/hooks 中的 husky 脚本 → 执行用户配置的命令。
   • 若命令执行失败，终止 Git 操作。

版本差异：

• Husky v4 ：直接修改 .git/hooks 脚本。
• Husky v8+ ：使用 .husky/_ 目录存储通用脚本，用户配置存放在 .husky 根目录。

---

3. simple-git-hook 工作原理

simple-git-hook 是一个轻量化的替代方案，核心设计目标是 简化配置 和 减少侵入性。其工作原理：

1. 配置方式 ：在 package.json 的 simple-git-hook 字段中定义 Hook 命令（如 pre-commit: "npm test"）。
2. 安装时 ：自动生成 .git/hooks 目录下的脚本，直接指向用户定义的命令。
3. 触发流程 ：
   • Git 事件触发 → 调用 .git/hooks 中的脚本 → 执行对应命令。

与 Husky 的差异：

• 无中间抽象层，直接生成原生 Git Hook 脚本。
• 不依赖隐藏目录（如 .husky），完全通过 package.json 配置。

---

4. 切换为何失效？

从 Husky 迁移到 simple-git-hook 时，常见问题包括：

原因 1：旧版本 Husky 残留文件

• 问题 ：Husky v4 直接在 .git/hooks 生成脚本，未完全卸载会导致残留文件与新工具冲突。
• 现象：Git 事件仍执行旧脚本，忽略 simple-git-hook 配置。

原因 2：Hook 脚本未正确生成

• 问题 ：未执行 simple-git-hook 的安装命令（如 npx simple-git-hook），或未触发 postinstall 生命周期。
• 现象 ：.git/hooks 目录下无对应脚本。

原因 3：路径或权限问题

• 问题：生成的 Hook 脚本路径错误，或脚本无执行权限（常见于 Linux/macOS）。
• 现象 ：执行时报错 Permission denied。

原因 4：配置格式差异

• 问题 ：simple-git-hook 要求命令为 字符串，而 Husky 支持函数或复杂语法。
• 现象：脚本因语法错误直接失败。

---

5. 解决方案

步骤 1：彻底清理旧工具

卸载 Husky 并删除残留文件：

# 卸载 Husky
npm uninstall husky

# 删除 .husky 目录（v8+）
rm -rf .husky

# 删除 .git/hooks 中的 Husky 脚本（v4）
rm -rf .git/hooks/*

步骤 2：正确安装 simple-git-hook

npm install simple-git-hook --save-dev

# 手动生成 Hook 脚本（若 postinstall 未触发）
npx simple-git-hook

步骤 3：检查脚本生成与权限

确认 .git/hooks 目录下存在对应脚本（如 pre-commit），并赋予执行权限：

chmod +x .git/hooks/pre-commit

步骤 4：配置格式修正

在 package.json 中按规范配置命令：

{
  "simple-git-hook": {
    "pre-commit": "npm run lint",
    "commit-msg": "npx commitlint --edit"
  }
}

注意：命令需为字符串，不支持函数或复杂表达式。

步骤 5：验证 Hook 是否生效

手动触发 Hook 测试：

# 模拟 pre-commit
.git/hooks/pre-commit

---

总结

工具切换失效的根源通常是 残留文件冲突 或 配置格式不兼容 。通过彻底清理旧工具、遵循新工具的配置规范，即可顺利完成迁移。对于轻量化场景，simple-git-hook 是比 husky 更简洁的选择，但需注意其灵活性与功能边界的差异。

---