Claude Code Hooks 2026 完整实战指南：六个生产可用的 Hook 场景，附完整脚本和配置

2026-04-27阅读 722热度 722

Claude

Hooks 到底是什么：Agent 生命周期的切面

如果你熟悉 Spring 的 AOP 或者 Git Hooks，那么理解 Claude Code Hooks 就毫不费力了：它允许你在 Agent 执行特定操作的前后，自动触发你预先定义好的逻辑。

整个生命周期如下图所示：

hook-lifecycle-events

其中，PreToolUse是最常用的事件——可以说，90% 的“安全护栏”需求都是在这里实现的。

配置文件放在哪：三级作用域

Hooks 的配置是一个 JSON 对象，需要放在 Claude Code 的 settings 文件里。根据不同的管理需求，有三个位置可供选择：

~/.claude/settings.json              # 全局：对所有项目生效
.claude/settings.json                # 项目级：随代码提交，团队共享
.claude/settings.local.json          # 本地：不提交，仅对自己生效

一个比较推荐的做法是：将通用的安全策略放在全局配置里，而项目特定的规则则放在.claude/settings.json中并提交到代码仓库。

配置文件的基本结构是这样的：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

这是一个三层嵌套结构：事件名 → 匹配器 → 处理器数组。其中，matcher使用正则表达式来匹配工具名，例如Bash只拦截命令行操作，Edit|Write拦截文件修改，mcp__.*则可以拦截所有 MCP 工具的调用。

场景一：拦截危险 Shell 命令

这是最高频的需求。创建一个脚本，专门拦截像rm -rf、DROP TABLE、git push --force这类危险操作。

#!/bin/bash
# .claude/hooks/block-dangerous-commands.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# 定义危险模式（使用正则匹配）
DANGEROUS_PATTERNS=(
  'rm\s+-rf\s+/'           # rm -rf 根目录或绝对路径
  'git\s+push\s+.*--force' # force push
  'DROP\s+TABLE'           # 删表
  'DROP\s+DATABASE'        # 删库
  'git\s+reset\s+--hard'   # 丢弃未提交修改
  '>\s*/dev/sd'            # 写入磁盘设备
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -iEq "$pattern"; then
    # 退出码 2 = 阻塞性错误，Claude 会收到拒绝通知
    echo "BLOCKED: 命令匹配危险模式 [$pattern]" >&2
    echo "原始命令: $COMMAND" >&2
    exit 2
  fi
done

# 通过检查，允许执行
exit 0

对应的配置如下：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-commands.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

这里有个关键细节：退出码的含义可能和直觉不同。退出码1表示非阻塞错误（Claude 会忽略并继续执行），而退出码2才是阻塞错误（Claude 会收到拒绝通知并停止操作）。一开始很容易误用exit 1，结果发现拦截逻辑根本没生效。

场景二：敏感文件保护

防止 Claude 修改.env、密钥文件、锁文件等你不希望被自动工具触碰的文件。

#!/bin/bash
# .claude/hooks/protect-sensitive-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 如果没有文件路径（比如 Bash 命令），直接放行
[ -z "$FILE_PATH" ] && exit 0

# 敏感文件模式
PROTECTED_PATTERNS=(
  '\.env$'
  '\.env\.'
  'credentials'
  'secret'
  '\.pem$'
  '\.key$'
  'package-lock\.json$'
  'pnpm-lock\.yaml$'
  'yarn\.lock$'
  'go\.sum$'
)

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if echo "$FILE_PATH" | grep -iEq "$pattern"; then
    echo "BLOCKED: 不允许修改敏感文件 $FILE_PATH" >&2
    exit 2
  fi
done

exit 0

配置时需要注意，matcher要匹配 Edit 和 Write 两个工具：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-sensitive-files.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

pretooluse-decision-flow

场景三：代码修改后自动 Lint

每次 Claude 编辑完文件，自动运行一遍 linter，并将结果反馈给它。这样一来，Claude 就能在同一轮对话中自动修复格式问题。

#!/bin/bash
# .claude/hooks/auto-lint.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE_PATH" ] && exit 0

# 根据文件类型选择对应的 linter
case "$FILE_PATH" in
  *.js|*.ts|*.jsx|*.tsx)
    RESULT=$(npx eslint --fix "$FILE_PATH" 2>&1) || true
    ;;
  *.py)
    RESULT=$(python -m ruff check --fix "$FILE_PATH" 2>&1) || true
    ;;
  *.go)
    RESULT=$(gofmt -w "$FILE_PATH" 2>&1) || true
    ;;
  *.ja va)
    # 只检查不修复，把问题反馈给 Claude
    RESULT=$(mvn checkstyle:check -pl "$(dirname "$FILE_PATH")" 2>&1 | tail -5) || true
    ;;
  *)
    exit 0
    ;;
esac

# 如果有 lint 问题，将其作为额外上下文反馈给 Claude
if [ -n "$RESULT" ]; then
  jq -n --arg result "$RESULT" --arg file "$FILE_PATH" '{
    hookSpecificOutput: {
      hookEventName: "PostToolUse",
      additionalContext: "Lint 结果 [\($file)]:\n\($result)\n如果有问题请修复。"
    }
  }'
fi

exit 0

注意，这个 Hook 配置在PostToolUse事件上，即在编辑完成之后触发：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-lint.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

场景四：SessionStart 自动注入项目上下文

每次新对话启动时，自动加载 Git 状态、最近的 issue、当前分支等信息，让 Claude 从一开始就掌握项目背景。

#!/bin/bash
# .claude/hooks/inject-context.sh

# 收集项目状态
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
RECENT_COMMITS=$(git log --oneline -5 2>/dev/null || echo "no commits")
DIRTY_FILES=$(git diff --name-only 2>/dev/null | head -10)
ISSUES=$(gh issue list -L 3 --json title,number --jq '.[] | "#\(.number) \(.title)"' 2>/dev/null || echo "GitHub CLI 不可用")

# 构建上下文
CONTEXT="当前分支: $BRANCH
最近 5 次提交:
$RECENT_COMMITS
未提交的修改:
${DIRTY_FILES:-无}
最近的 Issues:
${ISSUES:-无}"

jq -n --arg ctx "$CONTEXT" '{
  hookSpecificOutput: {
    hookEventName: "SessionStart",
    additionalContext: $ctx
  }
}'

exit 0

配置如下：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-context.sh",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

这个 Hook 有个细节需要注意：SessionStart事件的matcher可以区分startup（新对话）、resume（恢复对话）和compact（上下文压缩后）。通常我们只在startup时加载完整上下文，以避免在resume时重复注入信息。

hook-types-comparison

场景五：异步审计日志

记录 Claude 执行的所有操作，但不阻塞正常流程。关键在于设置"async": true——这意味着异步执行，不会影响 Agent 的响应速度。

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "async": true,
            "command": "echo \"$(date +%Y-%m-%dT%H:%M:%S) | $(jq -r '.tool_name') | $(jq -r '.tool_input | tostring' | head -c 200)\" >> \"$CLAUDE_PROJECT_DIR\"/.claude/audit.log"
          }
        ]
      }
    ]
  }
}

这里没有设置matcher，意味着所有工具调用都会被记录。日志输出格式类似这样：

2026-04-08T14:23:01 | Edit | {"file_path":"/src/main/ja va/Service.ja va","old_string":"...
2026-04-08T14:23:05 | Bash | {"command":"mvn compile -pl dlm-framework/dlm-rule"}
2026-04-08T14:23:12 | Read | {"file_path":"/src/test/ja va/ServiceTest.ja va"}

一旦出现问题，这份日志就能帮你完整回溯 Claude 的每一步操作。

场景六：HTTP Hook 对接外部合规系统

如果你的团队有独立的合规审核系统（例如安全扫描服务），可以使用 HTTP Hook 在执行前请求外部 API 进行校验：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/api/validate-command",
            "headers": {
              "Authorization": "Bearer $COMPLIANCE_TOKEN"
            },
            "allowedEnvVars": ["COMPLIANCE_TOKEN"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

HTTP Hook 会将工具调用的完整 JSON 数据作为 POST 请求体发送给你的服务。你的服务只需返回{"decision": "block", "reason": "..."}就能拦截该操作。

这在企业环境中特别有用——安全团队可以维护一个中心化的策略服务，所有开发者的 Claude Code 实例都通过 HTTP Hook 与之对接。

进阶：四种 Hook 类型怎么选

Claude Code 支持四种 Hook 类型，各自适用于不同的场景：

90% 的场景使用command类型就足够了。prompt和agent类型虽然功能强大，但每次触发都会消耗额外的 token，因此不建议在高频事件（如 PostToolUse）上使用。

pretooluse-decision-flow

常见问题

Q：Hook 脚本的 stdin 里具体传了什么？

不同工具的输入结构不同。Bash 工具会传入{"tool_input": {"command": "...", "description": "...", "timeout": ...}}，而 Edit 工具则传入{"tool_input": {"file_path": "...", "old_string": "...", "new_string": "..."}}。所有 Hook 都会收到session_id、cwd、permission_mode等公共字段。可以使用jq -r '.tool_input.command'来提取你需要的特定字段。

Q：Hook 执行失败会怎样？

这取决于退出码。退出码 0 表示成功，退出码 2 表示阻塞（Claude 会停止操作），其他任何退出码（包括 1）都视为非阻塞错误，仅记录到 debug 日志，Claude 会继续执行。这是新手最容易踩的坑——切记不要用exit 1来试图拦截操作。

Q：怎么调试 Hook？

在 Claude Code 中输入/hooks可以查看所有已加载的 Hook 配置。脚本的 stderr 输出会出现在 debug 日志里。建议在开发时，先在终端单独测试脚本：echo '{"tool_input":{"command":"rm -rf /"}}' | bash .claude/hooks/block-dangerous-commands.sh，检查退出码和输出是否符合预期。

Q：Hook 会拖慢 Claude 的执行速度吗？

同步 Hook 会。因此要注意两点：1）设置合理的timeout（默认 600 秒太长了，大多数场景 5-10 秒足够）；2）对于不需要阻塞的操作（如审计日志），务必使用"async": true进行异步执行。

Q：能在 Hook 里修改 Claude 的操作参数吗？

可以。PreToolUse的 Hook 可以在 JSON 输出中返回updatedInput字段来修改工具参数。例如，你可以把rm -rf dist/改成rm -rf dist/ --interactive，或者给 Bash 命令自动加上set -e。但需要谨慎使用这个功能——静默修改用户意图可能会造成困惑。

我的建议

Hooks 本质上是给 AI Agent 加 middleware。和 Web 开发里的中间件一样，最好的 Hook 是你写完就忘了它存在——它在背后默默工作，只在真正危险的时候跳出来拦你一下。

一个最小化且实用的配置通常包含三个 Hook：

PreToolUse/Bash：拦截rm -rf、--force、DROP等危险模式。
PreToolUse/Edit|Write：保护.env和锁文件等敏感文件。
PostToolUse/Edit|Write（async）：自动 lint 并记录审计日志。

这三个 Hook 组合起来，足以覆盖 95% 的“AI 编程事故”场景。剩下的 5%，就交给 Git 来兜底吧。