【Bug已解决】Git operation failed / husky pre-commit hook blocked — Claude Code Git 操作被钩子拦截解决方案

【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 被拒绝

原因分类表

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 # 步骤 2：Claude 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, chore

4. 各方案对比总结

5. 常见问题 FAQ

5.1 Claude Code 为什么不自动运行 lint

Claude 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 prepare

5.8 Claude Code 修改了不应该修改的文件

使用.claudeignore或在 CLAUDE.md 中指定哪些文件不应修改。

5.9 commitlint 报 "subject may not be empty"

确保 commit message 有描述部分：type(scope): description，description 不能为空。

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 格式符合 commitlint

6. 总结

1. 根本原因：Git 操作被拦截是因为 Claude Code 不了解项目的 husky/lint-staged 配置，修改的代码未通过 lint 检查或 commit message 不符合规范
2. 最佳实践：在项目根目录创建.claude/CLAUDE.md，声明项目的工具链（ESLint、Prettier、测试命令）和 Git 提交规范，让 Claude Code 遵循
3. 提交流程：让 Claude Code 在提交前先运行npm run lint和npm test，确认通过后再git add+git commit
4. 紧急情况：--no-verify可以临时跳过钩子，但后续必须手动修复 lint 错误并 amend 提交
5. 最佳实践建议：将完整的项目工具链和 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