Claude Code Hooks：自定义自动化工作流
什么是 Hooks
Hooks 是 Claude Code 提供的自动化扩展机制，允许你在特定事件发生时自动执行自定义脚本。通过 Hooks，你可以在 Claude 调用工具之前或之后插入自己的逻辑，比如自动格式化代码、阻止危险命令或发送通知。
Hooks 在你的本地机器上以确定性方式执行，不消耗 LLM 的 token，是构建可靠自动化工作流的理想方式。
Hook 事件类型
| 事件 | 触发时机 |
|---|---|
PreToolUse |
工具调用执行之前 |
PostToolUse |
工具调用执行之后 |
Notification |
Claude 发送通知时 |
Stop |
Claude 完成响应时 |
配置方法
Hooks 在 .claude/settings.json 中配置：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hook": {
"type": "command",
"command": "echo 'File is about to be modified'"
}
}
],
"PostToolUse": [
{
"matcher": "Edit|Write",
"hook": {
"type": "command",
"command": "npx prettier --write $CLAUDE_FILE_PATH"
}
}
]
}
}
matcher 字段支持正则表达式，用于匹配工具名称（如 Edit、Write、Bash 等）。
实战示例
文件保存后自动 Lint
{
"PostToolUse": [
{
"matcher": "Edit|Write",
"hook": {
"type": "command",
"command": "npx eslint --fix $CLAUDE_FILE_PATH 2>/dev/null || true"
}
}
]
}
阻止危险命令
{
"PreToolUse": [
{
"matcher": "Bash",
"hook": {
"type": "command",
"command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm\\s+-rf\\s+/|DROP\\s+DATABASE'; then echo 'BLOCKED: Dangerous command detected' >&2; exit 1; fi"
}
}
]
}
当 hook 脚本以非零状态退出时，对应的工具调用将被阻止。
完成时发送通知
{
"Stop": [
{
"matcher": "",
"hook": {
"type": "command",
"command": "osascript -e 'display notification \"Claude 完成了任务\" with title \"Claude Code\"'"
}
}
]
}
最佳实践
- 保持脚本快速：Hook 脚本会阻塞 Claude 的执行流程，避免长时间运行的任务
- 妥善处理错误：使用
|| true防止非关键脚本失败阻塞工作流 - 善用环境变量：Claude 会注入
$CLAUDE_FILE_PATH、$CLAUDE_TOOL_INPUT等上下文变量 - 团队共享：将 hooks 配置放在项目级
.claude/settings.json中，提交到仓库供团队共用
常见问题
Hooks 和 MCP 有什么区别？
Hooks 是确定性的本地脚本，在特定事件时自动触发，适合自动化检查和格式化。MCP 则是让 Claude 访问外部工具和数据源的协议，Claude 可以主动调用 MCP 提供的工具。两者互补，不冲突。
Hook 脚本执行失败会怎样？
如果 PreToolUse 的 hook 脚本以非零状态退出，对应的工具调用将被阻止。如果 PostToolUse 的脚本失败，Claude 会收到错误信息但会继续执行后续操作。
可以在 Hook 中使用哪些环境变量？
Claude Code 会自动注入上下文相关的环境变量，包括 CLAUDE_FILE_PATH（当前操作的文件路径）、CLAUDE_TOOL_INPUT（工具的输入参数）等。具体可用变量取决于触发的事件和工具类型。
