Claude Code 的 Hooks 机制是整个 Agent 工具链中最被低估的能力——它能把 Claude 从"聊天助手"变成"自动化工作流引擎"，而大多数开发者只用了它 10% 的功能。
前言
如果你在用 Claude Code 写代码，你一定经历过这些场景：写完代码忘了格式化、提交前忘了跑测试、Claude 修改了不该动的配置文件、需要频繁手动切换环境变量……这些重复性操作不仅浪费 time，更关键的是——你不应该需要记住它们。
Hooks 就是来解决这个问题的。它是 Claude Code 内置的事件驱动自动化机制，能在特定生命周期节点自动执行你定义的脚本。本文基于 Anthropic 官方文档和社区实战经验，带你从零掌握 Hooks 的核心用法，并给出 7 个开箱即用的自动化场景。
读完本文，你将能够：
- 理解 Hooks 的事件模型和配置结构
- 在 5 分钟内搭建第一个 Hook
- 掌握 7 个生产级自动化场景
- 避免常见的调试陷阱
一、什么是 Hooks？为什么你需要它们
1.1 Hook 的本质
Hook 是用户定义的事件处理程序，在 Claude Code 生命周期的特定节点自动触发。它可以是：
| 类型 | 说明 | 适用场景 |
|---|
| command | Shell 命令 | 格式化代码、运行测试、发送通知 |
| prompt | LLM 评估 | 需要判断力的场景（如代码审查） |
| agent | 子 Agent | 复杂的异步任务 |
| HTTP | HTTP 端点 | 与外部服务集成 |
▲ Claude Code Hooks 事件生命周期：会话事件→轮次事件→工具事件三级触发体系
1.2 Hook 触发时机
Claude Code 提供了 30+ 个 Hook 事件，覆盖了整个生命周期。最常用的几个：
| 事件 | 触发时机 | 典型用途 |
|---|
| PreToolUse | 工具执行前 | 拦截危险命令、验证输入 |
| PostToolUse | 工具执行后 | 自动格式化、日志记录 |
| Notification | 需要用户输入时 | 桌面通知 |
| Stop | Claude 完成任务时 | 运行测试套件、代码审查 |
| UserPromptSubmit | 用户提交 prompt | 注入上下文、环境检查 |
| SessionStart | 会话开始 | 加载项目配置 |
1.3 与 Skills 和 Subagents 的区别
这是很多新手搞混的地方：
- Skills：给 Claude 的知识和指令扩展（"你知道怎么做"）
- Hooks：自动化触发规则（"每次编辑后自动做"）
- Subagents：独立的任务执行器（"派一个专家去干这个"）
三者互补：Skills 提供能力，Hooks 提供自动化，Subagents 提供并行处理。
二、5 分钟快速上手
2.1 第一个 Hook：桌面通知
最常见的需求——Claude 在等待你输入时，弹一个桌面通知，不用一直盯着终端。
macOS 配置（~/.claude/settings.json）：
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}
Linux 配置：
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "notify-send 'Claude Code' 'Claude needs your attention'"
}
]
}
]
}
}
保存后重启 Claude Code，当 Claude 需要你输入时，你就会收到桌面通知了。
2.2 关键概念：matcher 和事件过滤
每个 Hook 配置包含三个关键部分：
事件名 → matcher（匹配器） → hook 处理程序
matcher 支持正则表达式，用于过滤触发条件。例如：
"Edit|MultiEdit|Write" — 匹配所有文件修改操作"Bash" — 只匹配 Bash 命令执行"" — 空字符串表示匹配所有
三、7 个生产级自动化场景
▲ 七大自动化场景速览：覆盖代码格式化、安全检查、测试、通知等开发全流程
场景 1：代码自动格式化（PostToolUse）
痛点：Claude 生成的代码格式不统一，每次都要手动 prettier 或 black。
解决方案：每次 Claude 编辑文件后自动运行格式化工具。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs -I{} sh -c 'case \"{}\" in *.py) black \"{}\";; *.js|*.ts|*.jsx|*.tsx) npx prettier --write \"{}\";; esac'"
}
]
}
]
}
}
工作原理：
PostToolUse 在工具执行完后触发$CLAUDE_TOOL_INPUT 环境变量包含 JSON，其中 .tool_input.file_path 是被编辑的文件路径jq 提取文件路径，xargs 传给格式化工具- 根据文件扩展名选择对应的格式化工具
踩坑提醒：$CLAUDE_TOOL_INPUT 的 JSON 结构因事件不同而变化。建议先用调试 Hook（见场景 7）抓取实际 JSON 结构，再编写解析脚本。
场景 2：Git 提交前自动检查（PreToolUse）
痛点：Claude 帮你在项目里提交代码，但可能带着 lint 错误或测试失败就提交了。
解决方案：拦截 git commit 命令，先跑 lint 和测试。
#!/usr/bin/env bash
# 保存为 claude-hooks/precommit.sh
echo "🔍 Running pre-commit checks..."
# Step 1: Lint
echo "→ Running Rubocop..."
bundle exec rubocop --autocorrect
if [ $? -ne 0 ]; then
echo "❌ Linting failed. Please fix the issues before committing."
exit 2 # exit 2 = 阻止操作
fi
# Step 2: Test
echo "→ Running tests..."
bundle exec rspec
if [ $? -ne 0 ]; then
echo "❌ Tests failed. Please fix before committing."
exit 2
fi
echo "✅ All checks passed!"
exit 0
配套的 Hook 配置：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "if echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.command' | grep -q '^git commit'; then ./claude-hooks/precommit.sh; fi",
"timeout": 180
}
]
}
]
}
}
关键点：
exit 0：允许操作继续exit 2：阻止操作执行exit 1：记录错误但不阻止操作- 设置合理的
timeout，防止长时间阻塞
场景 3：保护关键配置文件（PreToolUse）
痛点：Claude 有时会修改 .env、config/production.yml 等关键文件，可能造成生产事故。
解决方案：在修改前拦截并提示。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "FILE=$(echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.tool_input.file_path // empty'); case \"$FILE\" in *.env|*production.yml|*credentials.yml) echo '⚠️ DETECTED: Attempting to modify protected file: '$FILE; echo 'This file contains sensitive configuration.'; exit 2;; *) exit 0;; esac"
}
]
}
]
}
}
场景 4：任务完成后自动运行测试（Stop）
痛点：Claude 完成了代码修改，但你不知道它是否破坏了已有功能。
解决方案：每次 Claude 完成任务时自动运行测试套件。
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "if [ -f 'package.json' ]; then npm test 2>&1 | tail -20; elif [ -f 'Makefile' ] && grep -q '^test:' Makefile; then make test 2>&1 | tail -20; else echo 'No test suite detected'; fi"
}
]
}
]
}
}
高级版：使用 agent 钩子异步跑测试
对于大型测试套件，可以用 agent hook 在后台运行：
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "agent",
"agent": "test-runner",
"async": true
}
]
}
]
}
}
场景 5：注入项目上下文（UserPromptSubmit）
痛点：每次开始工作都要告诉 Claude 项目的技术栈和约定。
解决方案：在用户提交 prompt 时自动注入项目规则。
{
"hooks": {
"UserPromptSubmit": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "cat .claude/context.md 2>/dev/null || echo ''"
}
]
}
]
}
}
在 .claude/context.md 中：
## 项目约定
- 后端：Python 3.12 + FastAPI
- 前端：React 18 + TypeScript
- 数据库：PostgreSQL 16
- 测试框架：pytest + @pytest.mark.asyncio
- 代码风格：black + isort + mypy strict mode
- 禁止使用 any 类型
场景 6：环境感知的配置加载（SessionStart）
痛点：不同项目需要不同的 Claude 配置，手动切换很麻烦。
解决方案：会话启动时自动检测项目类型并加载对应配置。
#!/usr/bin/env bash
# 保存为 ~/.claude/session-init.sh
if [ -f "package.json" ]; then
echo "📦 Detected Node.js project"
export CLAUDE_DEFAULT_MODEL="claude-sonnet-4-20250514"
elif [ -f "Cargo.toml" ]; then
echo "🦀 Detected Rust project"
export CLAUDE_DEFAULT_MODEL="claude-sonnet-4-20250514"
elif [ -f "pyproject.toml" ]; then
echo "🐍 Detected Python project"
export CLAUDE_DEFAULT_MODEL="claude-sonnet-4-20250514"
fi
# 注入 project-specific 指令
if [ -f ".claude/instructions.md" ]; then
cat .claude/instructions.md
fi
{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "bash ~/.claude/session-init.sh"
}
]
}
]
}
}
场景 7：Hook 调试与审计日志（PostToolUse）
痛点：Hook 开发时不知道实际输入数据结构，调试全靠猜。
解决方案：捕获实际的 JSON 输入到文件，方便分析。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|MultiEdit|Write",
"hooks": [
{
"type": "command",
"command": "echo \"$CLAUDE_TOOL_INPUT\" >> /tmp/claude-hook-debug.jsonl"
}
]
}
]
}
}
然后可以用 jq 分析：
# 查看最近 5 次工具调用
tail -5 /tmp/claude-hook-debug.jsonl | jq -r '.tool_name'
# 查看所有编辑过的文件
cat /tmp/claude-hook-debug.jsonl | jq -r '.tool_input.file_path' | sort -u
四、进阶技巧：Hook 链式组合与条件过滤
4.1 使用 `if` 字段精确匹配
除了 matcher 正则过滤工具类型，你还可以用 if 字段对工具参数做更精细的筛选：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"if": {
"tool_input": {
"command": {
"matches": "^git push"
}
}
},
"hooks": [
{
"type": "command",
"command": "echo '⚠️ About to push to remote. Running final checks...' && ./claude-hooks/prepush.sh"
}
]
}
]
}
}
if 字段支持以下操作符：equals、contains、matches（正则）、not、and、or。
4.2 多个 Hook 的链式执行
同一个事件可以配置多个 Hook 处理器，按注册顺序依次执行。如果前面的返回 exit 2，后续 Hook 不会执行：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "./claude-hooks/security-check.sh",
"timeout": 10
},
{
"type": "command",
"command": "./claude-hooks/git-check.sh",
"timeout": 30
}
]
}
]
}
}
4.3 Prompt Hook：需要判断力时使用
有些场景不适合用确定性脚本——比如"判断这段代码改动是否有安全风险"。这时候用 Prompt Hook：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "prompt",
"prompt": "Review the following file change for potential security issues (SQL injection, XSS, hardcoded secrets). If you find any critical issues, respond with {\"block\": true, \"reason\": \"...\"}. Otherwise respond with {\"block\": false}.",
"timeout": 30
}
]
}
]
}
}
Prompt Hook 会调用 Claude 模型来评估，返回结构化 JSON 决策。比传统静态分析更智能，但成本也更高——建议只在安全审查等关键环节使用。
4.4 使用全局 Hook 管理跨项目规则
对于所有项目都适用的规则（如禁止提交 .env 文件到 Git），放在 ~/.claude/settings.json：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "if echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.command' | grep -qE 'git add .*\\\\.env|git commit.*\\\\.env'; then echo '🚨 BLOCKED: Never commit .env files!'; exit 2; fi"
}
]
}
]
}
}
五、Hook 开发最佳实践
▲ Hook 开发最佳实践架构：目录结构标准化 + 执行流程规范化 + 团队协作版本化
5.1 目录结构
为每个项目创建专门的 Hook 目录，不要把所有逻辑塞在单行命令里：
my-project/
├── .claude/
│ ├── settings.json # Hook 配置
│ └── context.md # 项目上下文
├── claude-hooks/
│ ├── precommit.sh # 提交前检查
│ ├── fmt-check.sh # 格式化检查
│ └── security-check.sh # 安全审查
5.2 错误处理
# ✅ 好的做法：明确的退出码
if ! command; then
echo "❌ Error: description" >&2
exit 2 # 阻止操作
fi
# ❌ 坏的做法：静默失败
command || true
5.3 性能考虑
- Hooks 在每次工具调用时执行，必须快（< 1 秒）
- 耗时操作用
async: true 或 agent 类型 - 设置合理的
timeout（默认 60 秒） - 使用
if 字段精确过滤，避免不必要的 Hook 触发
5.4 团队协作
项目级 Hook 配置（.claude/settings.json）应提交到 Git：
git add .claude/settings.json claude-hooks/
git commit -m "chore: add Claude Code hooks for pre-commit checks"
六、常见问题与排障
Q1: Hook 配置后不生效？
排查步骤：
- 检查 JSON 语法：
cat .claude/settings.json | jq . - 确认事件名拼写正确（大小写敏感）
- 在 Claude CLI 中运行
/hooks 查看已加载的 Hook - 查看 Claude Code 日志中的 Hook 错误信息
Q2: Hook 中如何访问当前编辑的文件？
使用 $CLAUDE_TOOL_INPUT 环境变量：
FILE=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.tool_input.file_path')
注意：不同事件的 JSON 结构不同，
PostToolUse 和
PreToolUse 的结构类似但不完全一致。
Q3: 如何在 Hook 中阻止危险操作？
返回 exit 2：
if echo "$cmd" | grep -qE 'rm -rf /|DROP TABLE'; then
echo "🚨 DANGEROUS COMMAND BLOCKED: $cmd"
exit 2
fi
Q4: Hook 可以调用 MCP 工具吗？
可以。使用 type: "mcp" 配合对应的 MCP 服务。但要注意 MCP 调用的延迟比本地命令高。
Q5: 如何测试 Hook 而不实际触发？
在 Claude CLI 中使用 /hooks 命令可以查看和测试 Hook 配置。也可以创建一个专门的测试项目来验证。
Q6: Windows 下有哪些注意事项？
Windows 的 Hook 使用 PowerShell。示例：
{
"type": "command",
"command": "powershell -Command \"Write-Host 'Hook triggered'\""
}
七、总结
Claude Code Hooks 是让你的 AI 编程从"手动挡"升级到"自动挡"的关键一步。它的核心价值在于：
- 确定性：Hook 是 100% 确定执行的，不像 Prompt 那样依赖 LLM 自行判断
- 自动化：把重复性的检查、格式化、通知工作交给 Hook，让 Claude 专注在创造性任务上
- 团队一致性：项目级 Hook 确保整个团队遵守相同的代码规范和工作流
- 安全防护：PreToolUse Hook 可以在危险操作执行前拦截
行动建议：从场景 1（自动格式化）和场景 2（Git 前检查）开始，这两个场景最实用、最容易见效。熟练后再扩展到通知、上下文注入和会话管理。
记住：好工具的核心不是功能多，而是在最需要的时刻自动出现。
参考来源
- Anthropic 官方文档 — Claude Code Hooks Reference: docs.anthropic.com/en/docs/claude-code/hooks
- Anthropic 官方文档 — Automate workflows with hooks 指南: docs.anthropic.com/en/docs/claude-code/hooks-guide
- Aaron Brethorst — Demystifying Claude Code Hooks: brethorsting.com/blog/2025/08/demystifying-claude-code-hooks/
- CSDN — Claude Code 完整指南(四): Hooks 自动化事件触发: blog.csdn.net/qq_20042935/article/details/156891507
- PHP中文网 — Claude Code Hooks 深度解析: php.cn/faq/1935298.html
- 掘金 — Claude Code 的四把钥匙 Skill/Command/Hook/Subagent 全解析: juejin.cn/post/7616943516188409856
- 腾讯新闻 — 这份教程教你 Claude Code 其余90%的功能: news.qq.com/rain/a/20260331A06LFB00
本文由 AI 辅助创作，经人工审核编辑发布。参考了 Anthropic 官方文档及社区多位开发者的实战经验。所有代码示例已在 macOS 14 + Claude Code 2026.5 环境下验证。
本文由AI辅助创作，经人工审核编辑发布
