教程

Claude Code Hooks 完全指南：用确定性脚本守护每次代码变更的自动化护栏

Claude Code Hooks 完整教程：与 CLAUDE.md 规则的本质区别（每次都执行 vs 建议性）、四种 Hook 类型（PreToolUse/PostToolUse/Stop/Notification）、自动 lint、测试自动运行、阻止危险操作、任务完成通知，以及前端项目完整 Hooks 配置示例。

2026/4/186分钟 阅读ClaudeEagle

Claude Code 的 CLAUDE.md 规则是"建议性的"——Claude 会尽量遵守，但不保证每次都执行。Hooks 不同：Hooks 每次都执行，不依赖模型的判断。

这个差异很重要。CLAUDE.md 里写"每次修改后运行 lint"，Claude 可能忘。Hooks 里配置同样的规则，lint 就会每次在修改后自动运行。

Hooks 是什么

Hooks 是绑定在 Claude Code 工具调用生命周期上的脚本：

  • PreToolUse：工具调用之前执行（可以阻止）
  • PostToolUse：工具调用之后执行
  • Notification：有通知时执行
  • Stop：Claude 完成任务时执行

与 CLAUDE.md 规则的区别：

特性CLAUDE.md 规则Hooks
执行保证模型"尽量"遵守每次都执行
可以阻止操作❌✅（PreToolUse exit 1）
适合场景风格指南、偏好安全守卫、自动化
复杂逻辑有限任意 shell 脚本

配置位置

json
// .claude/settings.json（项目级）
// 或 ~/.claude/settings.json（全局级）
{
  "hooks": {
    "PostToolUse": [...],
    "PreToolUse": [...],
    "Stop": [...],
    "Notification": [...]
  }
}

PostToolUse Hooks：每次修改后自动执行

1. 自动 Lint + 格式化

json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "cd $(git rev-parse --show-toplevel) && npm run lint --fix 2>&1 | tail -5"
          }
        ]
      }
    ]
  }
}

效果：每次 Claude 修改文件后自动运行 lint，修复风格问题，不需要手动触发。

2. 自动运行受影响的测试

json
{
  "PostToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "bash -c 'FILE=\"$CLAUDE_TOOL_INPUT_PATH\"; TEST_FILE=\"${FILE%.ts}.test.ts\"; [ -f \"$TEST_FILE\" ] && npx jest \"$TEST_FILE\" --passWithNoTests 2>&1 | tail -10 || echo \"No test file found\"'"
      }]
    }
  ]
}

效果：修改 auth.service.ts 时，自动检查是否有对应的 auth.service.test.ts，有的话自动运行。

3. 自动提交检查（git status 通知）

json
{
  "PostToolUse": [
    {
      "matcher": "Write|Edit|MultiEdit",
      "hooks": [{
        "type": "command",
        "command": "git diff --stat HEAD 2>/dev/null | tail -3"
      }]
    }
  ]
}

效果：每次文件修改后，显示当前的 git 改动统计，保持对改动范围的可见性。

PreToolUse Hooks：在执行前拦截

1. 阻止写入生产配置文件

json
{
  "PreToolUse": [
    {
      "matcher": "Write|Edit|MultiEdit",
      "hooks": [{
        "type": "command",
        "command": "bash -c 'FILE=\"$CLAUDE_TOOL_INPUT_PATH\"; if echo \"$FILE\" | grep -qE \"(production|prod|.env.production)\"; then echo \"ERROR: 禁止直接修改生产配置文件: $FILE\"; exit 1; fi'"
      }]
    }
  ]
}

效果：如果 Claude 试图写入文件名包含 production 或 .env.production 的文件，直接阻止并报错。

2. 阻止危险的 bash 命令

json
{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "bash -c 'CMD=\"$CLAUDE_TOOL_INPUT_COMMAND\"; if echo \"$CMD\" | grep -qE \"(rm -rf|DROP TABLE|DELETE FROM.*WHERE 1=1)\"; then echo \"ERROR: 潜在危险命令被拦截: $CMD\"; exit 1; fi'"
      }]
    }
  ]
}

效果：在 Claude 执行 bash 命令之前检查，拦截 rm -rf、DROP TABLE 等危险操作。

3. 在操作前备份重要文件

json
{
  "PreToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "bash -c 'FILE=\"$CLAUDE_TOOL_INPUT_PATH\"; if echo \"$FILE\" | grep -qE \"(config|settings|.env)\"; then cp \"$FILE\" \"${FILE}.backup.$(date +%Y%m%d_%H%M%S)\" 2>/dev/null && echo \"备份已创建: ${FILE}.backup.*\"; fi'"
      }]
    }
  ]
}

效果：修改配置文件前自动备份，文件名带时间戳。

Stop Hooks：任务完成时通知

发 Telegram 通知

json
{
  "Stop": [
    {
      "hooks": [{
        "type": "command",
        "command": "bash -c 'curl -s -X POST \"https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage\" -d \"chat_id=${TELEGRAM_CHAT_ID}&text=Claude+Code+任务完成\" > /dev/null'"
      }]
    }
  ]
}

效果：Claude 完成一个长任务时，自动发 Telegram 通知，不需要一直盯着终端。

播放系统提示音（macOS）

json
{
  "Stop": [
    {
      "hooks": [{
        "type": "command",
        "command": "afplay /System/Library/Sounds/Glass.aiff 2>/dev/null || true"
      }]
    }
  ]
}

实战配置：前端项目完整 Hooks 设置

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [{
          "type": "command",
          "command": "bash -c 'FILE=\"$CLAUDE_TOOL_INPUT_PATH\"; if echo \"$FILE\" | grep -q \".env.production\"; then echo \"ERROR: 拒绝修改生产环境文件\"; exit 1; fi'"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "cd $(git rev-parse --show-toplevel 2>/dev/null || echo .) && npx eslint \"$CLAUDE_TOOL_INPUT_PATH\" --fix --quiet 2>&1 | grep -v 'npm warn' | head -10 || true"
          },
          {
            "type": "command",
            "command": "bash -c 'FILE=\"$CLAUDE_TOOL_INPUT_PATH\"; TEST=\"${FILE%.tsx}.test.tsx\"; [ -f \"$TEST\" ] && npx vitest run \"$TEST\" --reporter=verbose 2>&1 | tail -8 || true'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "echo '✅ Claude Code 任务完成' && git diff --stat HEAD 2>/dev/null | tail -5"
        }]
      }
    ]
  }
}

Hooks 调试技巧

查看 Hooks 输出：Claude Code 在输出面板显示 Hook 执行结果。如果 Hook 有 echo 输出，能在终端看到。

测试 Hook 命令：在 Hook 正式使用前，先在终端单独运行命令验证：

bash
# 模拟 Hook 环境变量并测试
CLAUDE_TOOL_INPUT_PATH="src/auth.ts" bash -c '你的hook命令'

处理 Hook 失败：

bash
# 非零退出码 = 阻止操作（PreToolUse）
# 给 PostToolUse Hook 加 || true，防止 Hook 本身的失败影响 Claude
command || true

常见 Hooks 模式总结

需求Hook 类型核心命令
每次修改后 lintPostToolUsenpm run lint --fix
自动运行对应测试PostToolUsejest ${file.test.ts}
阻止写入生产配置PreToolUse + exit 1grep production && exit 1
拦截危险命令PreToolUse + exit 1grep "rm -rf" && exit 1
任务完成时通知StopTelegram/Slack API 调用
操作前备份文件PreToolUsecp file file.backup
追踪改动范围PostToolUsegit diff --stat

来源：morphllm.com Claude Code Hooks 指南 | Anthropic 官方 Hooks 文档 | 整理：ClaudeEagle

相关文章推荐

教程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教程Claude Code Hooks 完全指南：自动化工作流的利器Claude Code Hooks 是在工具执行生命周期特定节点触发自定义脚本的机制。本文涵盖全部 17 种 Hook 事件，配置格式、实战案例（阻止危险命令、自动 lint、任务通知），以及异步 Hook 用法和最佳实践，助你构建强大的自动化工作流。2026/2/27教程Claude Code Routines 完全指南：10 个开箱即用的 AI 自动化开发任务模板Claude Code Routines 实战指南：定时触发和事件触发配置语法，10 个开箱即用模板（依赖漏洞扫描/技术债追踪/夜间重构/PR 初审/周报生成等），以及幂等性、错误处理最佳实践。2026/4/16教程Claude Code 定时任务完整指南：每天自动 review 代码、检查依赖、生成日报Claude Code 定时任务完整配置指南：Desktop 本地任务、云端任务、/loop 三种方式对比，含 5 个实用任务模板（每日代码 review、依赖漏洞扫描、技术债报告），以及权限防卡死和补跑机制详解。2026/4/13