解决 Husky pre-commit 钩子失败问题

问题描述

在进行 git commit 操作时，可能会遇到以下错误提示：

husky > pre-commit hook failed (add --no-verify to bypass)

同时可能伴随其他错误信息，例如：

'pretty-quick' is not recognized as an internal or external command,
operable program or batch file.

这表明 Git 的 pre-commit 钩子（由 husky 管理）执行失败，阻止了提交操作。

根本原因分析

Husky 是一个 Git 钩子管理工具，用于在提交代码前运行各种检查（如代码格式化、语法检查、测试等）。pre-commit 钩子失败通常有以下几种原因：

1. 依赖包缺失或未正确安装
2. Husky 配置冲突或损坏
3. 脚本配置不正确
4. 版本兼容性问题

解决方案

方案一：删除并重新安装 Git 钩子（推荐）

注意

此操作不会影响您的 Git 版本历史记录，只会重置 Git 钩子配置

# 删除现有的 Git 钩子目录
rm -rf .git/hooks

# 重新安装项目依赖（这会重新生成 husky 钩子）
npm install

方案二：检查并修复依赖问题

如果错误信息显示特定命令未找到（如 pretty-quick、eslint 等）：

# 全局安装缺失的工具（不推荐，可能引起版本冲突）
npm install -g eslint prettier pretty-quick

# 更好的做法：作为开发依赖安装到项目中
npm install --save-dev eslint prettier pretty-quick

方案三：更新 Husky 到最新版本

Husky 的较新版本（v9+）解决了许多已知问题：

# 更新 husky
npm install --save-dev husky@latest

# 重新设置 husky
npm pkg set scripts.prepare="husky install"
npm run prepare

方案四：检查并修正 package.json 配置

确保 package.json 中的脚本配置正确：

{
  "scripts": {
    "lint": "eslint \"src/**/*.{js,ts,tsx}\" --quiet --fix",
    "precommit": "lint-staged",
    "prepare": "husky install"
  },
  "lint-staged": {
    "**/*": "prettier --write --ignore-unknown"
  }
}

如果不需要 pre-commit 检查，可以移除相关配置：

{
  "scripts": {
    // 移除 precommit 脚本
    // "precommit": "lint-staged",
  }
}

方案五：临时解决方案（不推荐）

注意

此方法会绕过所有提交前检查，可能导致未经验证的代码被提交

git commit -m "提交信息" --no-verify

或者临时禁用钩子路径：

git config --unset core.hooksPath

最佳实践建议

1. 保持依赖更新：定期更新 husky 和相关代码质量工具
2. 统一开发环境：确保所有团队成员使用相同的工具版本
3. 明确脚本职责：为不同的代码检查任务创建清晰的脚本
4. 使用 lint-staged：只对暂存的文件进行检查，提高效率

版本兼容性说明

某些情况下，版本不兼容会导致问题：

# 如果 prettier v3 有问题，可以降级到 v2
npm install --save-dev prettier@2.8.8

总结

Husky pre-commit 钩子失败通常是由于配置问题或依赖缺失引起的。推荐首先尝试删除 .git/hooks 目录并重新安装依赖，这样可以解决大多数问题。如果问题依旧，检查具体的错误信息并相应安装缺失的依赖包。

避免长期使用 --no-verify 选项，因为它会绕过重要的代码质量检查，可能导致代码库质量下降。