Hooks 是 Claude Code 中一个强大但常被忽视的功能。通过在特定生命周期事件触发自定义脚本，你可以实现安全检查、自动格式化、通知发送等各种自动化工作流。
什么是 Hooks？
Hooks 是用户定义的 Shell 命令或 LLM Prompt，在 Claude Code 生命周期的特定节点自动执行。当事件触发时，Claude Code 将 JSON 格式的上下文传递给 Hook 处理器，处理器可以检查输入、采取行动，并可选地返回决策。
Hook 生命周期事件
| 事件 | 触发时机 |
|---|---|
SessionStart | 会话开始或恢复时 |
UserPromptSubmit | 你提交 Prompt，Claude 处理前 |
PreToolUse | 工具调用执行前，可以阻止 |
PermissionRequest | 出现权限对话框时 |
PostToolUse | 工具调用成功后 |
PostToolUseFailure | 工具调用失败后 |
Notification | Claude Code 发送通知时 |
SubagentStart | 子 Agent 被创建时 |
SubagentStop | 子 Agent 完成时 |
Stop | Claude 完成响应时 |
TeammateIdle | Agent 团队成员即将空闲时 |
TaskCompleted | 任务被标记完成时 |
ConfigChange | 会话中配置文件变更时 |
WorktreeCreate | 通过 --worktree 创建工作树时 |
WorktreeRemove | 工作树被移除时 |
PreCompact | 上下文压缩前 |
SessionEnd | 会话终止时 |
Hook 配置格式
在 .claude/settings.json 中配置 Hooks：
json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/block-rm.sh"
}
]
}
]
}
}实战案例 1：阻止危险命令
以下示例展示如何使用 PreToolUse Hook 阻止 rm -rf 等破坏性命令：
Hook 脚本 .claude/hooks/block-rm.sh：
bash
#!/bin/bash
COMMAND=$(cat | jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q 'rm -rf'; then
jq -n '{
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "deny",
permissionDecisionReason: "Destructive command blocked by hook"
}
}'
else
exit 0
fi工作流程：
- Claude Code 决定执行
Bash "rm -rf /tmp/build" PreToolUse事件触发，匹配Bash- 运行 hook 脚本，检测到
rm -rf - Hook 返回
deny决策 - Claude Code 阻止该命令
实战案例 2：文件保存后自动 lint
bash
#!/bin/bash
# PostToolUse hook - 文件保存后自动运行 lint
TOOL=$(cat | jq -r '.tool')
if [ "$TOOL" = "Write" ] || [ "$TOOL" = "Edit" ]; then
npm run lint --silent 2>/dev/null
fi实战案例 3：会话开始时加载项目状态
bash
#!/bin/bash
# SessionStart hook
echo "=== 项目状态 ==="
git status --short 2>/dev/null
echo "未完成 TODO 数量: $(grep -r 'TODO' src/ 2>/dev/null | wc -l)"实战案例 4：任务完成后发送通知
bash
#!/bin/bash
# Stop hook - Claude 完成响应后发送系统通知
# macOS:
osascript -e 'display notification "Claude Code 已完成任务" with title "Claude Code"' 2>/dev/null
# Linux:
# notify-send "Claude Code" "任务已完成"异步 Hooks
对于不需要阻止工具执行的 Hook，使用异步模式避免影响响应速度：
json
{
"hooks": {
"PostToolUse": [
{
"hooks": [
{
"type": "command",
"command": ".claude/hooks/log-usage.sh",
"async": true
}
]
}
]
}
}退出码含义
| 退出码 | 含义 |
|---|---|
0 | 成功，允许操作继续 |
非 0 | 失败，具体行为取决于事件类型 |
| JSON 输出 | 返回结构化决策（如 permissionDecision） |
最佳实践
- 保持脚本简洁：Hook 在工具调用关键路径上执行，避免耗时操作
- 异步非关键任务：日志、通知等设为
async: true - 测试充分：Hook 错误可能中断工作流，确保脚本健壮
- 使用版本控制：将
.claude/hooks/纳入 git，与团队共享安全策略 - 最小权限原则：只在必要时使用
deny决策
总结
Claude Code Hooks 提供了强大的扩展机制，让你能够在 AI 助手的工作流中插入自定义逻辑。无论是安全防护、代码质量检查还是工作流自动化，Hooks 都是实现这些需求的理想工具。
来源：Claude Code 官方文档 - Hooks Reference 原文作者：Anthropic Team