教程

Claude Code Hooks 官方完整指南：28 个事件、JSON 输出和安全拦截实战

Claude Code Hooks 官方文档完整中文整理：Hook 生命周期、28 个事件表、matcher 与 if 条件、PreToolUse 安全拦截、PostToolUse 自动化、JSON 输出格式、exit code 行为、HTTP hooks、异步 hooks、MCP tool hooks，以及一套可直接复用的团队安全配置。

2026/5/156分钟 阅读ClaudeEagle

Hooks 是 Claude Code 最适合做"确定性自动化"的机制。CLAUDE.md 能告诉 Claude "尽量这样做"，Hooks 则能在关键生命周期点自动执行脚本、HTTP 请求或 Prompt，并且可以拦截危险操作。

Hooks 适合解决什么问题？

典型场景：

  • 安全拦截：阻止 rm -rf、git push --force、读取 .env 等高风险操作
  • 自动格式化：文件写入后自动运行 prettier、eslint --fix、go fmt
  • 审计记录：记录 Claude 执行过的 Bash 命令、修改过的文件
  • 环境管理：进入不同目录时自动加载 direnv 或项目环境
  • CI/脚本准备：用 Setup 事件做一次性初始化
  • 上下文治理：在 PreCompact / PostCompact 前后保存关键状态

一句话：凡是"每次都必须发生"的动作，用 Hooks；凡是"希望 Claude 遵守"的规则，用 CLAUDE.md。

Hook 生命周期：三类触发节奏

Claude Code Hooks 按触发频率分三类：

  1. 会话级：SessionStart、SessionEnd、Setup
  2. 回合级：UserPromptSubmit、Stop、StopFailure
  3. 工具级：PreToolUse、PostToolUse、PostToolUseFailure、PostToolBatch

此外还有配置、文件、工作树和 MCP 相关事件。

28 个 Hook 事件速查

事件触发时机常见用途
SessionStart会话开始或恢复打印项目状态、加载环境摘要
Setup--init-only 或 CI 初始化一次性准备依赖、缓存
UserPromptSubmit用户 Prompt 提交前Prompt 审计、注入过滤
UserPromptExpansionSlash/Skill 展开前阻止危险命令展开
PreToolUse工具调用前安全拦截、权限决策
PermissionRequest权限弹窗出现自动审批/记录
PermissionDeniedauto mode 拒绝工具调用允许模型重试某些安全替代方案
PostToolUse工具成功后格式化、测试、日志
PostToolUseFailure工具失败后收集错误、重试建议
PostToolBatch并行工具批次完成后批量汇总、统一检查
NotificationClaude 发送通知推送到 Slack/Discord
SubagentStartSubagent 启动记录并行任务
SubagentStopSubagent 结束汇总子任务结果
TaskCreatedTaskCreate 创建任务任务审计
TaskCompleted任务标记完成任务统计
StopClaude 完成回复自动摘要、保存结果
StopFailureAPI 错误结束错误上报
TeammateIdleAgent team 队友即将 idle自动分配后续任务
InstructionsLoadedCLAUDE.md 或 rules 加载检查规则是否生效
ConfigChange配置文件改变重新验证配置
CwdChanged工作目录改变切换环境变量
FileChanged监听文件变化外部编辑同步
WorktreeCreate创建 Worktree替换默认 Git 行为
WorktreeRemove删除 Worktree清理临时资源
PreCompact上下文压缩前保存计划和关键状态
PostCompact压缩完成后恢复摘要和上下文
ElicitationMCP 请求用户输入审计外部工具交互
ElicitationResult用户回应 MCP 请求后过滤敏感输入

配置结构：matcher + if + handler

Hooks 通常写在 .claude/settings.json：

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

三个核心概念：

  • matcher：先按工具名或事件范围匹配，例如 Bash、Edit|Write、*
  • if：进一步按子命令过滤，例如 Bash(rm *)
  • hooks：真正执行的 handler，可以是 command、HTTP endpoint 或 prompt

if 很重要：它能避免每个 Bash 命令都启动脚本，降低开销。

实战：阻止危险 rm 命令

.claude/hooks/block-rm.sh：

bash
#!/bin/bash
CMD_TO_CHECK=`jq -r '.tool_input.command'`

if echo "${CMD_TO_CHECK}" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0
fi

工作流：

  1. Claude 想执行 Bash "rm -rf /tmp/build"
  2. PreToolUse 事件触发
  3. matcher: Bash 命中
  4. if: Bash(rm *) 命中
  5. 脚本读取 stdin JSON，返回 permissionDecision: deny
  6. Claude Code 阻止工具调用，并把原因反馈给模型

PostToolUse：文件修改后自动检查

json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --fix"
          }
        ]
      }
    ]
  }
}

适合：

  • TypeScript 项目：npm run lint -- --fix
  • Go 项目：gofmt -w
  • Python 项目：ruff check --fix && ruff format
  • Rust 项目：cargo fmt

注意：这类 hook 应该保持快速，避免每次编辑都跑完整测试。全量测试更适合 Stop 或手动 Skill。

推荐团队基线配置

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm -rf *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/deny-dangerous.sh"
          },
          {
            "type": "command",
            "if": "Bash(git push --force*)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/deny-force-push.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-changed-files.sh"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/save-session-state.sh"
          }
        ]
      }
    ]
  }
}

Hooks vs CLAUDE.md vs Skills

需求用什么原因
每次修改后自动格式化Hooks确定性执行
写 API 时遵循响应格式CLAUDE.md / rules持续性规则
发布到 staging 的完整流程Skills步骤化任务
阻止危险命令Hooks必须强制执行
代码审查清单Skills按需加载，避免常驻上下文

最佳实践

  1. 安全类 hook 用 deny，不要只打印 warning
  2. 格式化 hook 要快，慢检查放到 Stop 或 CI
  3. 脚本读取 stdin JSON，不要依赖脆弱的环境变量
  4. 配置进 .claude/settings.json，团队共享；个人实验放 .claude/settings.local.json
  5. Hook 脚本放 .claude/hooks/，并提交到 Git
  6. 避免重复：Hook 已经自动 lint，就不要在 CLAUDE.md 里写"每次都运行 lint"

来源：Claude Code 官方文档 - Hooks reference | 整理：ClaudeEagle

相关文章推荐

教程Claude Code Hooks 完全实战指南：自动化你的编码工作流Claude Code Hooks 完整实战指南：6 种 Hook 事件类型（PreToolUse/PostToolUse/PreCompact/PermissionDenied/Stop/SubagentStop）；8 个完整配置示例（文件修改后自动 lint+格式化/TypeScript 类型检查/git commit 前强制测试/危险命令阻断/Auto Mode 拒绝通知/MCP 工具调用/PreCompact 快照/条件 hooks）；Hook 脚本环境变量说明；以及 5 个最佳实践（|| true 防误报/输出简洁/脚本快速/exit 1 明确阻断/逻辑放独立脚本）。2026/5/6教程Claude Code Hooks 深度实战：5 个真实案例教你用自动化消灭重复工作Claude Code Hooks 完整实战指南：配置文件结构（.claude/hooks/）、四种触发时机（post_write/pre_commit/session_start/session_end），以及 5 个完整案例：自动 Lint+格式化、修改后运行相关测试、TypeScript 类型检查、提交前安全扫描、Session 开始加载工作状态。含 on_error 策略选择。2026/4/22教程Claude Code Hooks 完全指南：用确定性脚本守护每次代码变更的自动化护栏Claude Code Hooks 完整教程：与 CLAUDE.md 规则的本质区别（每次都执行 vs 建议性）、四种 Hook 类型（PreToolUse/PostToolUse/Stop/Notification）、自动 lint、测试自动运行、阻止危险操作、任务完成通知，以及前端项目完整 Hooks 配置示例。2026/4/18教程Claude Code Hooks 实战指南：5 大自动化场景、三种 Hook 类型与故障排查Claude Code Hooks 实战指南：/hooks 交互菜单四步创建桌面通知 Hook、5 大常用自动化场景（等待通知/编辑后 Prettier 格式化/退出码 2 阻止受保护文件/PostCompact 重注入上下文/ConfigChange 审计日志）、四种 Hook 类型（command/prompt-based/agent-based/HTTP Webhook）、输入/输出机制（stdin JSON/stdout 注入上下文/退出码 0 继续/2 阻止/非零警告）、结构化 JSON 输出、Matcher 过滤器语法（Edit|Write/Bash(git *)/*/空字符串）、四级存储位置，以及五大故障排查方法和调试技巧。2026/3/8教程Claude Code Hooks 完全指南：五大自动化场景、三类 Hook 类型与 JSON 输入输出规范Claude Code Hooks 完整指南：30 秒创建第一个 Hook（/hooks 交互菜单）、五大常用场景（通知/自动格式化/保护文件/压缩后注入上下文/审计配置变更）、六个生命周期事件（PreToolUse/PostToolUse/Notification/PostCompact/SessionStart/Stop）、四类 Hook 类型（Command/Prompt/Agent/HTTP）、JSON 输入输出规范（decision/reason/output/updatedInput）、Matcher 过滤语法，以及五大故障排查方法。2026/3/6教程Claude Code Hooks 实战指南：自动格式化、桌面通知与文件保护Claude Code Hooks 实战指南：5 大场景（桌面通知、自动格式化、文件保护、压缩后注入上下文、配置审计）的完整配置，Hook 输入/输出 JSON 格式，事件类型（PreToolUse/PostToolUse/Notification/PostCompact），以及提示型和 Agent 型 Hook。2026/3/2