Claude Code中生命周期Hooks的使用指南介绍

目录

• 概述
• Hook 的 4 种类型
• 4 个生命周期事件
• Setup
• SessionStart
• UserPromptSubmit
• SessionEnd
• Hook 命令通用字段
• HTTP 类型特有字段
• Prompt 类型特有字段
• 配置位置
• 用户级（全局生效）
• 项目级（仅当前项目）
• 实用示例
• 1. 每次启动加载项目文档
• 2. 提交前做代码规范检查
• 3. HTTP webhook 通知
• 4. 项目初始化时安装依赖
• 注意事项

Hooks 是用户自定义的脚本/命令，在 Claude Code 的特定生命周期节点自动执行。支持 4 种类型、4 个生命周期事件。

类型	type 字段	说明
Shell 命令	"command"	执行 shell 命令，stdout 作为输出
HTTP 请求	"http"	向指定 URL 发送 POST 请求（含 hook input JSON）
LLM 提示	"prompt"	用 LLM 评估 prompt，返回结构化结果
Agent 验证	"agent"	用 agent 执行验证任务（如检查测试是否通过）

在 Claude Code 启动时运行一次，用于项目初始化。

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

触发时机： 进程启动后、REPL 渲染前 Hook Input 字段：

字段	类型	说明
hook_event_name	"Setup"	—
trigger	"init" | "maintenance"	触发来源
session_id	string	当前会话 ID
cwd	string	工作目录
transcript_path	string	会话日志路径

stdout 处理： ❌ 不注入模型

每次会话开始时执行。新启动、/resume、/clear 后都会触发。stdout 内容作为 system message 注入模型上下文。

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

触发时机：

source	场景
startup	进程首次启动
resume	--resume 或 /resume 恢复会话
clear	/clear 后
compact	上下文压缩后

Hook Input 字段：

字段	类型	说明
hook_event_name	"SessionStart"	—
source	"startup" | "resume" | "clear" | "compact"	触发来源
agent_type	string (optional)	agent 类型
model	string (optional)	当前模型

stdout 处理： ✅ 注入为 system message，模型可见

用户每次提交消息前执行。可以对用户输入做预处理、追加安全检查或上下文。

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

Hook Input 字段：

字段	类型	说明
hook_event_name	"UserPromptSubmit"	—
prompt	string	用户输入的原始文本

stdout 处理： ✅ 注入为 system message，模型可见

会话结束时执行（进程退出、/clear）。用于清理资源、记录日志。

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

Hook Input 字段：

字段	类型	说明
hook_event_name	"SessionEnd"	—
reason	"clear" | "resume" | "logout" | "prompt_input_exit" | "other"	结束原因

stdout 处理： ❌ 不注入模型，静默执行

超时控制： 默认 1.5s，可通过 CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS 环境变量配置

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

字段	类型	必填	说明
type	"command" | "http" | "prompt" | "agent"	✅	Hook 类型
command / prompt / url	string	✅	具体命令/prompt/URL（依 type 而异）
timeout	number	❌	超时时间（秒）
statusMessage	string	❌	执行时 spinner 显示的自定义消息
once	boolean	❌	仅执行一次后自动移除
if	string	❌	条件过滤（权限规则语法，如 "Bash(git *)"）
async	boolean	❌	后台异步执行，不阻塞主流程（仅 command 类型）
asyncRewake	boolean	❌	后台执行且 exit code 2 时唤醒模型（仅 command 类型，隐含 async）

字段	类型	说明
url	string	POST 请求目标 URL（hook input 以 JSON body 发送）
headers	object	自定义请求头，支持 $VAR 环境变量引用
allowedEnvVars	string[]	允许在 header 值中插值的环境变量白名单

字段	类型	说明
prompt	string	LLM 评估 prompt，用 $ARGUMENTS 占位符引用 hook input JSON
model	string	使用的模型（默认小模型）

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 }
        ]
      }
    ]
  }
}

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

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

{
  "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"]
          }
        ]
      }
    ]
  }
}

{
  "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.5s 且被 failsafe（5s）兜底
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 中声明

以上就是Claude Code中生命周期Hooks的使用指南介绍的详细内容，更多关于Claude Code生命周期Hooks的资料请关注风君子博客其它相关文章！