husky钩子不执行的常见原因是什么？

Question

husky钩子不执行的常见原因是什么？ 一个常见的原因是未正确安装 Husky 或 Git 钩子未被激活。当通过 npm 安装 husky 后，若未运行 npx husky install 或未在 package.json 的 prepare 脚本中配置该命令，Git 就无法触发对应的钩子脚本。此外，项目根目录缺少 .husky 目录或钩子文件权限不足（如缺少可执行权限）也会导致钩子失效。使用 git commit 命令时看似无反应，实则钩子被跳过。确保 husky 正确初始化并检查 .git/hooks/ 中是否有对应脚本链接，是排查此类问题的关键步骤。

Answer 1

一、Husky 钩子不执行的常见原因分析（由浅入深）

• 1. Husky 未初始化或安装不完整
• 在通过 npm install husky --save-dev 安装后，若未运行 npx husky install，则 Git 钩子系统不会被激活。Husky v5+ 要求显式调用该命令来生成 .husky 目录并链接钩子。
• 2. prepare 脚本缺失
• 推荐在 package.json 中添加：

  "scripts": {
    "prepare": "husky install"
  }

  此脚本能确保每次执行 npm install 后自动初始化 Husky 钩子环境。
• 3. .husky 目录不存在或结构异常
• Husky 的钩子脚本应存放在项目根目录下的 .husky/ 文件夹中，如 .husky/pre-commit。若该目录缺失或文件为空，钩子无法触发。

二、权限与操作系统兼容性问题

问题类型	表现形式	解决方案
文件无执行权限	Linux/macOS 下报错 “Permission denied”	运行 chmod +x .husky/*
Windows Git Bash 权限模拟失效	钩子脚本未被执行	确认 Git for Windows 设置支持 execute bit
WSL 与 Windows 跨系统文件同步问题	权限丢失或路径错误	在 WSL 内部完成 husky install 操作

三、Git 钩子链接机制失效排查

Husky 实际上是通过在 .git/hooks/ 目录下创建指向 .husky/ 中脚本的符号链接来实现钩子注入。可通过以下命令验证：

ls -la .git/hooks/

预期输出应包含类似：

pre-commit -> ../../.husky/pre-commit

若链接缺失或断裂，则需重新运行 npx husky install 并手动检查钩子注册状态。

四、高级配置与 CI/CD 环境中的陷阱

1. CI 环境默认跳过 Git hooks：多数 CI 平台（如 GitHub Actions、GitLab CI）使用 shallow clone 或不启用本地钩子，需显式调用 lint/test 脚本替代。
2. 使用 --no-verify 提交绕过钩子：团队成员可能无意中使用 git commit --no-verify 导致钩子未执行，需加强代码审查流程。
3. Husky 版本迁移问题：从 v4 升级至 v7+ 时，配置方式由 huskyrc 迁移至 .husky/ 目录结构，旧项目易遗漏重构步骤。
4. 编辑器或 IDE 集成工具自动提交：如 VS Code 的 Source Control 功能可能绕过 CLI 钩子，建议关闭“自动提交”或配置 IDE 使用带 hook 的终端命令。
5. Node.js 版本不一致导致脚本解析失败：某些 pre-commit 脚本依赖特定版本的 Node 解释器，应在 .nvmrc 或 .node-version 中统一版本。
6. 钩子脚本返回非零退出码但未中断流程：检查脚本逻辑是否正确抛出错误，避免静默失败。
7. 多包管理器混合使用（npm/yarn/pnpm）：不同包管理器对 prepare 脚本的执行策略不同，建议统一规范并文档化。

五、诊断流程图（Mermaid 格式）

graph TD
    A[执行 git commit] --> B{Husky 钩子是否触发?}
    B -- 否 --> C[检查 .git/hooks/ 是否有符号链接]
    C --> D{链接存在且指向 .husky/?}
    D -- 否 --> E[运行 npx husky install]
    D -- 是 --> F[检查 .husky/pre-commit 是否可执行]
    F --> G{chmod +x .husky/* ?}
    G -- 否 --> H[添加执行权限]
    G -- 是 --> I[查看脚本内容是否正确]
    I --> J[确认 package.json 有 prepare 脚本]
    J --> K[排查 CI 或 IDE 提交路径]
    B -- 是 --> L[正常执行]