Claude Code 生命周期 Hooks 完整使用指南：从零开始掌握回调方法与高级实战技巧

Claude Code Hooks 核心概念

Hooks 本质上是你在 Claude Code 中预设的自定义脚本或命令，能够在指定的生命周期节点自动触发。这套体系支持 4 种类型，覆盖 4 个关键生命周期事件。

Hook 的 4 种类型详解

4 个生命周期事件

Setup

在 Claude Code 进程启动时仅执行一次，专门处理项目初始化工作。

{"hooks": {"Setup": [{"matcher": "","hooks": [{ "type": "command", "command": "npm install", "timeout": 60 }]}]}}

注意：该 hook 的 stdout 内容不会注入给 Claude 模型。

SessionStart

每次会话开始时触发。无论是全新启动、通过 /resume 恢复、还是 /clear 清空后，都会执行。其 stdout 内容会作为 system message 注入到模型上下文中。

{"hooks": {"SessionStart": [{"matcher": "","hooks": [{ "type": "command", "command": "cat .claude/session-context.md", "timeout": 10 }]}]}}

Hook Input 字段：

此处 stdout 会注入为 system message，模型能够读取。

UserPromptSubmit

在用户每次提交消息之前执行。适合对用户输入做预处理，比如插入安全检查或补充上下文信息。

{"hooks": {"UserPromptSubmit": [{"matcher": "","hooks": [{"type": "command","command": "node scripts/validate-input.js","timeout": 10,"statusMessage": "Validating input..."}]}]}}

该 hook 的 stdout 同样会作为 system message 注入，模型可见。

SessionEnd

会话结束时触发，例如进程退出或执行 /clear。常用于清理资源、记录日志等收尾工作。

{"hooks": {"SessionEnd": [{"matcher": "","hooks": [{ "type": "command", "command": "node scripts/cleanup.js", "timeout": 5 }]}]}}

该 hook 的 stdout 不会注入模型，静默执行。超时控制方面，默认值为 1.5 秒，可通过环境变量 CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS 自定义。

Hook 命令通用字段

所有类型的 hook 均支持以下字段：

HTTP 类型特有字段

Prompt 类型特有字段

配置位置

hooks 配置存放在 settings.json 中，支持两个层级：

用户级（全局生效）

位于 ~/.claude/settings.json：

{"hooks": {"SessionStart": [{"matcher": "","hooks": [{ "type": "command", "command": "echo 'Hello from global hook'", "timeout": 5 }]}]}}

项目级（仅当前项目）

位于项目根目录下的 .claude/settings.json：

{"hooks": {"Setup": [{"matcher": "","hooks": [{ "type": "command", "command": "npm install", "timeout": 120 }]}],"SessionStart": [{"matcher": "","hooks": [{ "type": "command", "command": "cat .claude/instructions.md", "timeout": 5 }]}],"UserPromptSubmit": [{"matcher": "","hooks": [{"type": "command","command": "scripts/lint-check.sh","timeout": 15,"if": "Write"}]}],"SessionEnd": [{"matcher": "","hooks": [{ "type": "command", "command": "scripts/cleanup.sh", "timeout": 5 }]}]}}

实用示例

1. 每次启动加载项目文档

这个场景非常实用——让 Claude Code 启动时自动加载项目文档，确保模型掌握项目背景。

{"hooks": {"SessionStart": [{"matcher": "","hooks": [{"type": "command","command": "cat .claude/project-guide.md","timeout": 5,"statusMessage": "Loading project guide..."}]}]}}

2. 提交前做代码规范检查

在用户每次提交前，自动运行代码规范检查，提前拦截问题。

{"hooks": {"UserPromptSubmit": [{"matcher": "","hooks": [{"type": "command","command": "node scripts/check-code-style.js "$CLAUD_PROMPT"","timeout": 10}]}]}}

3. HTTP webhook 通知

会话结束时，通过 HTTP 请求通知外部系统，例如将会话摘要推送到团队协作平台。

{"hooks": {"SessionEnd": [{"matcher": "","hooks": [{"type": "http","url": "https://api.example.com/claude-end","timeout": 5,"headers": {"Authorization": "Bearer $MY_API_TOKEN"},"allowedEnvVars": ["MY_API_TOKEN"]}]}]}}

4. 项目初始化时安装依赖

新项目首次启动时，自动检查并安装依赖，省去手动操作。

{"hooks": {"Setup": [{"matcher": "","hooks": [{"type": "command","command": "test -f package.json && npm install || echo 'No package.json found'","timeout": 120,"statusMessage": "Installing dependencies..."}]}]}}

注意事项

最后列出几个容易踩坑的关键点：

1. 超时控制：timeout 字段单位是秒。Setup 和 SessionStart 默认无严格限制，但 SessionEnd 默认仅 1.5 秒，并且有一个 failsafe 机制在 5 秒后会兜底。
2. stdout 注入：SessionStart 和 UserPromptSubmit 的 stdout 会作为 system message 发送给模型；Setup 和 SessionEnd 则不会，设计意图明确。
3. 异步执行：async: true 的 command hook 会在后台运行，不阻塞主流程。asyncRewake: true 更高级，若 exit code 为 2，可以唤醒模型处理错误。
4. 条件过滤：if 字段使用权限规则语法（例如 "Bash(git *)"、"Write"），只有匹配时才会执行，避免无关操作触发 hook。
5. once：设置为 true 的 hook 执行一次后自动从配置中移除，适合仅需单次运行的场景。
6. 安全：http hook 的 header 中如需引用环境变量，必须在 allowedEnvVars 显式声明，否则不生效。

来源：互联网