【Bug已解决】Git operation failed / husky pre-commit hook blocked — Claude Code Git 操作被钩子拦截解决方案1. 问题描述在 Claude Code 中执行 git 相关操作如 commit、push时操作被 git hooks 拦截终端弹出以下错误Error: git commit failed husky pre-commit hook failed (exit code 1) ✖ eslint --fix - Failed to run eslint: 12 errors found或者Error: git push failed remote: pre-receive hook declined ! [remote rejected] main - main (pre-receive hook declined)有时报错为 commit-msg 钩子拦截Error: git commit failed husky commit-msg hook failed ✖ commitlint: commit message does not conform to conventional commits这个问题在以下场景中特别常见Claude Code 自动生成的 commit message 不符合项目规范Claude Code 修改的代码未通过 eslint/prettier 检查项目使用 husky lint-staged 但 Claude Code 不了解这些工具pre-push 钩子运行测试但测试未通过企业 Git 服务器有服务端钩子限制# 典型复现过程 $ claude 提交当前的修改 # Claude Code 执行 git commit -m fix: update auth logic husky pre-commit hook failed ✖ eslint --fix Error: 3 errors found in src/auth.js # Claude Code 的修改未通过 lint 检查2. 原因分析核心原理拆解Claude Code 执行 git commit → 触发 pre-commit hook ↓ Hook 运行 eslint/prettier/tests → 检查失败 ↓ Hook 返回非零退出码 ↓ git commit 被拒绝原因分类表原因分类具体表现占比ESLint/Prettier 检查失败Claude 修改的代码有 lint 错误约 40%Commit message 不规范不符合 conventional commits约 25%测试未通过pre-push 钩子运行测试失败约 20%类型检查失败TypeScript 编译错误约 10%服务端钩子拒绝企业 Git 服务器策略约 5%3. 解决方案方案一让 Claude Code 修复 lint 错误后重试最推荐# 步骤 1告诉 Claude Code lint 失败 git commit 失败了eslint 有错误请修复后再提交 # Claude Code 会: # 1. 运行 eslint 查看具体错误 # 2. 修复错误 # 3. 重新提交 # 步骤 2如果 Claude Code 不了解项目的 lint 配置 先运行 npm run lint 查看所有错误然后逐一修复方案二在 CLAUDE.md 中告知 Git 规范# 步骤 1创建或编辑项目级 CLAUDE.md cat .claude/CLAUDE.md EOF # Git 提交规范 - 使用 conventional commits 格式: type(scope): description - type: feat/fix/docs/style/refactor/test/chore - 提交前必须通过 npm run lint 和 npm run test - 不要使用 --no-verify 跳过 hooks # Lint 配置 - 使用 ESLint Prettier - 修复所有错误后再提交 EOF # 步骤 2Claude Code 会自动遵循这些规范方案三让 Claude Code 先运行 lint 和测试# 在提交前让 Claude Code 验证 先运行 npm run lint 和 npm test 确保通过然后再提交 # Claude Code 会: # 1. 运行 npm run lint # 2. 修复所有 lint 错误 # 3. 运行 npm test # 4. 确认全部通过后提交方案四使用 --no-verify 临时跳过钩子不推荐# 步骤 1告诉 Claude Code 使用 --no-verify 使用 git commit --no-verify 提交 # ⚠️ 警告: 这会跳过所有 pre-commit 检查 # 仅在以下情况使用: # - 紧急修复需要快速提交 # - Hook 配置有问题 # - 后续会修复 lint 问题 # 步骤 2后续必须手动修复 lint 问题 npm run lint -- --fix git commit --amend --no-edit方案五配置 Claude Code 了解项目的 husky 配置# 步骤 1在 CLAUDE.md 中说明 husky 配置 cat .claude/CLAUDE.md EOF # 项目工具链 - 包管理器: pnpm - Lint: ESLint (运行 pnpm lint 检查, pnpm lint:fix 修复) - 格式化: Prettier (运行 pnpm format) - 测试: Vitest (运行 pnpm test) - Git Hooks: Husky lint-staged - pre-commit: 运行 eslint prettier on staged files - commit-msg: commitlint (conventional commits) - pre-push: 运行所有测试 # 提交流程 1. pnpm lint:fix 2. pnpm test 3. git add -A 4. git commit -m type(scope): description EOF方案六修复 commit message 格式# 步骤 1如果 commitlint 失败使用正确格式 使用 conventional commits 格式重新提交: feat(auth): add JWT token validation # 步骤 2如果 Claude Code 不了解格式 commit message 必须遵循: type(scope): description type 可以是: feat, fix, docs, style, refactor, test, chore4. 各方案对比总结方案适用场景推荐指数难度方案一修复后重试Lint 错误⭐⭐⭐⭐⭐低方案二CLAUDE.md 规范预防问题⭐⭐⭐⭐⭐低方案三先验证再提交通用预防⭐⭐⭐⭐⭐低方案四--no-verify紧急情况⭐⭐低方案五配置工具链长期方案⭐⭐⭐⭐⭐中方案六修复 messageCommitlint⭐⭐⭐⭐低5. 常见问题 FAQ5.1 Claude Code 为什么不自动运行 lintClaude Code 不了解项目的工具链配置。需要在 CLAUDE.md 中告知项目使用哪些工具和提交流程。5.2 --no-verify 是否安全不安全。--no-verify跳过所有 pre-commit 检查可能导致有 lint 错误或测试失败的代码被提交。仅在紧急情况下使用后续必须修复。5.3 如何让 Claude Code 总是生成规范的 commit message在 CLAUDE.md 中明确指定 commit message 格式和示例。Claude Code 会遵循 CLAUDE.md 中的指令。5.4 lint-staged 检查了未修改的文件lint-staged 只检查 staged 文件。如果报错涉及未修改的文件可能是 lint-staged 配置问题。检查.lintstagedrc配置。5.5 pre-push 钩子运行时间太长可以在 CLAUDE.md 中告知 Claude Code 使用--no-verify跳过 pre-push如果测试已在提交前运行过。但确保提交前已手动运行测试。5.6 企业 Git 服务器拒绝 push服务端钩子无法绕过。需要按照企业规范修改代码或 commit message。联系仓库管理员了解具体限制。5.7 husky 钩子未安装# 检查 husky 是否安装 npx husky install # 或 npm run prepare5.8 Claude Code 修改了不应该修改的文件使用.claudeignore或在 CLAUDE.md 中指定哪些文件不应修改。5.9 commitlint 报 subject may not be empty确保 commit message 有描述部分type(scope): descriptiondescription 不能为空。5.10 排查清单速查表□ 1. 在 CLAUDE.md 中声明项目的 Git 规范和工具链 □ 2. 提交前让 Claude Code 运行 npm run lint □ 3. 提交前让 Claude Code 运行 npm test □ 4. 使用 conventional commits 格式的 commit message □ 5. 不要使用 --no-verify 除非紧急情况 □ 6. 检查 husky lint-staged 配置 □ 7. 修复所有 lint 错误后再 git add □ 8. 服务端钩子无法绕过需遵守企业规范 □ 9. 在 CLAUDE.md 中提供完整的提交流程 □ 10. 确认 commit message 格式符合 commitlint6. 总结根本原因Git 操作被拦截是因为 Claude Code 不了解项目的 husky/lint-staged 配置修改的代码未通过 lint 检查或 commit message 不符合规范最佳实践在项目根目录创建.claude/CLAUDE.md声明项目的工具链ESLint、Prettier、测试命令和 Git 提交规范让 Claude Code 遵循提交流程让 Claude Code 在提交前先运行npm run lint和npm test确认通过后再git addgit commit紧急情况--no-verify可以临时跳过钩子但后续必须手动修复 lint 错误并 amend 提交最佳实践建议将完整的项目工具链和 Git 规范写入 CLAUDE.md这是让 Claude Code 自动遵守项目规范的最有效方法故障排查流程图flowchart TD A[Git 操作被 hook 拦截] -- B{哪个 hook 失败?} B --|pre-commit| C[运行 npm run lint 检查] B --|commit-msg| D[检查 commit message 格式] B --|pre-push| E[运行 npm test 检查] C -- F{有 lint 错误?} F --|是| G[让 Claude Code 修复错误] F --|否| H[检查 lint-staged 配置] D -- I{格式是否正确?} I --|否| J[使用 conventional commits 格式] I --|是| K[检查 commitlint 配置] E -- L{测试通过?} L --|否| M[让 Claude Code 修复测试] L --|是| N[检查 pre-push 脚本] G -- O[重新 git add commit] J -- O M -- O O -- P{提交成功?} P --|是| Q[✅ 问题解决] P --|否| R[在 CLAUDE.md 中添加项目规范] R -- S[Claude Code 遵循规范自动提交] S -- Q
