第 8 章：Hooks（自动化钩子）

本章概览

在前面的章节中，我们学习了 MCP 如何连接外部工具、Plugin 如何扩展工作流。本章要介绍的 Hooks 则解决了另一个问题——让 Claude Code 在特定事件发生时自动执行操作，无需每次手动触发。

学习目标

理解什么是 Hooks，它能做什么
掌握 Hooks 的事件类型
学会在 settings.json 中配置 Hooks
了解实用的 Hooks 场景和示例
理解 Hooks 和 MCP 的区别

8.1什么是 Hooks？

8.1.1一个类比

假设你有一位勤劳的助手（Claude Code），你可以给他设定一些"规矩"：

每次写完代码后，自动运行代码格式化工具 -> 这就是 Hook
每次修改文件后，自动运行测试 -> 这也是 Hook
任务完成后，自动发一条通知给你 -> 这还是 Hook

Hooks 就是一组自动触发的规则：当某个事件发生时，自动执行你预设的命令。

8.1.2正式定义

Hooks 是 Claude Code 提供的事件驱动自动化机制。你可以配置在特定事件（如工具调用前后、任务完成时）自动执行 shell 命令，从而实现自动化工作流。

Hooks 的核心价值

减少重复操作 —— 不用每次都手动提醒 Claude "记得格式化代码"
保证一致性 —— 每次操作后都自动检查，不会遗漏
透明可控 —— 你完全掌控什么时候执行什么命令
确定性执行 —— 不同于提示词的不确定性，Hooks 是代码级别的精确执行

8.1.3Hooks vs 在 CLAUDE.md 中写规则

你可能会问："我在 CLAUDE.md 中写'每次修改代码后运行测试'不也行吗？"

对比项	CLAUDE.md 规则	Hooks
执行保证	Claude 可能忘记遵守	100% 确定执行
执行方式	Claude 自己决定如何执行	精确的 shell 命令
灵活性	自然语言描述，灵活但模糊	精确的代码定义
适用场景	软性指导和偏好	硬性自动化需求

简单来说：CLAUDE.md 是"建议"，Hooks 是"规矩"。

8.2Hooks 事件类型

8.2.1支持的事件

Claude Code 支持以下几种 Hook 事件：

事件名称	触发时机	典型用途
PreToolUse	Claude 调用工具之前	拦截或验证工具调用
PostToolUse	Claude 调用工具之后	自动格式化、运行测试
Notification	Claude 发送通知时	发送自定义通知
Stop	Claude 完成回复/任务结束时	汇总、日志记录、通知
SubagentStop	子代理（subagent）完成任务时	管理子代理任务
UserPromptSubmit	用户提交提示词时（发送前）	验证或转换用户输入
SessionStart	新的 Claude Code 会话启动时	初始化环境、设置工作区
PreCompact	上下文压缩（compact）之前	在压缩前保存关键信息

8.2.2事件流程图

用户发送请求
     │
     ▼
Claude 分析请求，决定调用某个工具
     │
     ├── 【PreToolUse Hook 触发】── 自动执行预设命令
     │
     ▼
Claude 执行工具操作（如编辑文件）
     │
     ├── 【PostToolUse Hook 触发】── 自动执行预设命令
     │
     ▼
Claude 继续处理或完成任务
     │
     ├── 【Stop Hook 触发】── 自动执行预设命令
     │
     ▼
完成

8.2.3PreToolUse 详解

PreToolUse 在工具执行之前触发，你可以用它来：

验证操作 —— 检查即将执行的操作是否符合规范
拦截危险操作 —— 阻止某些不安全的操作
准备环境 —— 在操作前做一些准备工作

可以匹配的工具名称：

工具名称	说明
`Write`	写入文件
`Edit`	编辑文件
`Bash`	执行 shell 命令
`WebFetch`	获取网页内容
`Glob`	文件搜索
`Grep`	内容搜索
`Read`	读取文件

8.2.4PostToolUse 详解

PostToolUse 在工具执行之后触发，你可以用它来：

代码格式化 —— 每次写入文件后自动格式化
运行测试 —— 每次修改代码后自动运行测试
代码检查 —— 每次编辑后自动运行 linter
记录变更 —— 记录每次操作的日志

8.2.5Stop 详解

Stop 在 Claude 完成整个回复或一轮对话结束时触发：

发送通知 —— 任务完成后通知你
生成摘要 —— 自动生成本次操作的摘要
清理环境 —— 清理临时文件

8.3 配置 Hooks

8.3.1 配置文件位置

Hooks 配置写在 settings.json 文件中，和 MCP 一样分为项目级和用户级：

级别	文件路径	适用范围
项目级	`.claude/settings.json`	仅当前项目
用户级	`~/.claude/settings.json`	所有项目

8.3.2 配置格式

基本的配置格式如下：

json

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolName",
        "hooks": [
          {
            "type": "command",
            "command": "shell-command-to-execute"
          }
        ]
      }
    ]
  }
}

完整配置结构说明：

json

{
  "hooks": {
    "PreToolUse": [                   // 事件名称
      {
        "matcher": "Write",           // 匹配条件（可选）：匹配特定工具
        "hooks": [                    // hooks 数组：要执行的操作列表
          {
            "type": "command",        // 类型：command 表示执行 shell 命令
            "command": "echo 'About to write a file'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",      // 可以用 | 匹配多个工具
        "hooks": [
          {
            "type": "command",
            "command": "npm run format"
          }
        ]
      }
    ],
    "Stop": [
      {
        // 没有 matcher 表示匹配所有情况
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Task completed!' >> ~/claude-log.txt"
          }
        ]
      }
    ]
  }
}

8.3.3 配置字段详解

配置采用三层嵌套结构：事件 -> 匹配器组 -> hooks 数组。

匹配器组（matcher group）字段：

字段	类型	必填	说明
`matcher`	string	否	正则表达式，匹配工具名称。省略则匹配所有工具
`hooks`	array	是	要执行的操作列表

hooks 数组中每个元素的字段：

字段	类型	必填	说明
`type`	string	是	操作类型，见下方支持的类型列表
`command`	string	是（当 type 为 command 时）	要执行的 shell 命令

支持的 Hook 类型（type）

command —— 执行 shell 命令（最常用，本章示例均使用此类型）
prompt —— 向 Claude 发送一条提示词，让 Claude 处理并响应
agent —— 生成一个独立的子代理（subagent）来执行任务，不影响主对话
http —— 发送 HTTP POST 请求到指定 URL（适合与 Webhook 集成）

本教程的示例主要使用 command 类型。其他类型适用于更高级的自动化场景。

matcher 匹配规则

"matcher": "Write" —— 精确匹配 Write 工具
"matcher": "Write|Edit" —— 匹配 Write 或 Edit 工具
"matcher": ".*" —— 匹配所有工具（和省略 matcher 效果一样）
省略 matcher 字段 —— 匹配所有情况

8.3.4 Hook 命令如何获取事件数据

Hook 命令执行时，Claude Code 会通过 stdin（标准输入） 传入一个 JSON 对象，包含当前事件的详细信息。你需要在命令中解析这个 JSON 来获取所需数据（推荐使用 jq 工具）。

stdin JSON 常见字段：

JSON 字段	说明	适用事件
`.tool_name`	当前工具名称	PreToolUse, PostToolUse
`.tool_input`	工具的输入参数对象	PreToolUse, PostToolUse
`.tool_input.file_path`	操作的文件路径	PreToolUse, PostToolUse（文件相关工具）
`.tool_input.command`	执行的命令	PreToolUse, PostToolUse（Bash 工具）
`.tool_output`	工具的输出结果	PostToolUse
`.session_id`	当前会话 ID	所有事件
`.transcript_path`	对话记录文件路径	Stop

可用的环境变量：

环境变量	说明
`CLAUDE_PROJECT_DIR`	当前项目的根目录路径
`CLAUDE_CODE_ENTRYPOINT`	Claude Code 的启动方式（如 `cli`、`vscode` 等）

重要提示

早期文档中出现的 $CLAUDE_TOOL_NAME、$CLAUDE_FILE_PATH、$CLAUDE_EXIT_CODE 等环境变量并不存在。所有事件数据都通过 stdin JSON 传入，请使用 jq 解析。

解析 stdin JSON 的基本模式：

bash

# 单字段提取
FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path')

# 多字段提取（注意 stdin 只能读取一次，需先保存）
INPUT=$(cat /dev/stdin)
TOOL=$(echo $INPUT | jq -r '.tool_name')
FILE_PATH=$(echo $INPUT | jq -r '.tool_input.file_path')

使用示例：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"File modified: $(cat /dev/stdin | jq -r '.tool_input.file_path')\" >> ~/claude-changes.log"
          }
        ]
      }
    ]
  }
}

8.4 实用 Hooks 示例

8.4.1 示例 1：自动代码格式化

每次 Claude 写入或编辑文件后，自动运行 Prettier 格式化：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path'); npx prettier --write \"$FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

关于 2>/dev/null || true

2>/dev/null —— 隐藏错误输出（比如格式化非代码文件时的报错）
|| true —— 即使命令失败也不影响 Claude 继续工作

8.4.2 示例 2：自动运行 ESLint 检查

每次修改 JavaScript/TypeScript 文件后，自动运行 ESLint：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path'); if echo \"$FILE_PATH\" | grep -qE '\\.(js|ts|jsx|tsx)$'; then npx eslint \"$FILE_PATH\" --fix 2>/dev/null || true; fi"
          }
        ]
      }
    ]
  }
}

8.4.3 示例 3：自动运行测试

每次修改代码文件后，自动运行相关测试：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path'); if echo \"$FILE_PATH\" | grep -qE '\\.(js|ts|py)$'; then npm test 2>/dev/null || true; fi"
          }
        ]
      }
    ]
  }
}

注意

自动运行测试可能会显著拖慢 Claude 的响应速度。如果测试套件比较大，建议：

只在特定文件变更时运行测试
只运行相关的单元测试，而不是完整测试套件
或者改用 Stop 事件，在一轮任务结束后统一运行测试

8.4.4 示例 4：任务完成通知

Claude 完成任务时发送桌面通知（macOS）：

json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code 任务已完成\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Windows 版本（使用 PowerShell）：

json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell -Command \"[System.Windows.MessageBox]::Show('Claude Code 任务已完成', 'Claude Code')\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

跨平台通知（使用 node-notifier）：

json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx -y node-notifier-cli notify -t 'Claude Code' -m '任务已完成'"
          }
        ]
      }
    ]
  }
}

8.4.5 示例 5：变更日志记录

记录 Claude 所有的文件修改到日志文件：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path'); echo \"$(date '+%Y-%m-%d %H:%M:%S') - Modified: $FILE_PATH\" >> .claude/change-log.txt"
          }
        ]
      }
    ]
  }
}

日志文件 .claude/change-log.txt 的内容示例：

2024-01-15 14:32:15 - Modified: src/components/Login.tsx
2024-01-15 14:32:45 - Modified: src/styles/login.css
2024-01-15 14:33:10 - Modified: src/api/auth.ts
2024-01-15 14:35:00 - Modified: tests/login.test.ts

8.4.6 示例 6：Git 自动暂存

每次修改文件后，自动将文件添加到 Git 暂存区：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path'); git add \"$FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

8.4.7 示例 7：PreToolUse 拦截示例

阻止 Claude 修改特定目录中的文件：

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path'); if echo \"$FILE_PATH\" | grep -q 'config/production'; then echo 'BLOCKED: Cannot modify production config files' >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

PreToolUse 的拦截机制

当 PreToolUse Hook 命令返回退出码 2 时，Claude Code 会阻止该工具的执行。退出码 0 表示放行，退出码 1 仅产生一条非阻塞的警告信息（工具仍会执行）。因此，要真正拦截操作请务必使用 exit 2。

8.5 完整的项目配置示例

以下是一个前端项目的完整 Hooks 配置示例：

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path'); if echo \"$FILE_PATH\" | grep -q '.env'; then echo 'BLOCKED: Cannot modify .env files' >&2; exit 2; fi"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path'); if echo \"$FILE_PATH\" | grep -qE '\\.(js|ts|jsx|tsx|css|json|md)$'; then npx prettier --write \"$FILE_PATH\" 2>/dev/null || true; fi"
          },
          {
            "type": "command",
            "command": "FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path'); if echo \"$FILE_PATH\" | grep -qE '\\.(js|ts|jsx|tsx)$'; then npx eslint \"$FILE_PATH\" --fix 2>/dev/null || true; fi"
          },
          {
            "type": "command",
            "command": "FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path'); echo \"$(date '+%Y-%m-%d %H:%M:%S') - Modified: $FILE_PATH\" >> .claude/change-log.txt"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx -y node-notifier-cli notify -t 'Claude Code' -m '任务已完成' 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

这个配置做了什么：

PreToolUse：阻止 Claude 修改 .env 文件（保护敏感配置）
PostToolUse（第 1 个）：修改文件后自动运行 Prettier 格式化
PostToolUse（第 2 个）：修改 JS/TS 文件后自动运行 ESLint 修复
PostToolUse（第 3 个）：记录所有文件变更到日志
Stop：任务完成后发送桌面通知

8.6 Hooks 与 MCP 的区别

这是很多同学容易混淆的概念，我们来做一个清晰的对比：

8.6.1 概念对比

MCP（Model Context Protocol）
├── 作用：扩展 Claude 能"做什么"
├── 方向：Claude → 外部世界
├── 触发：Claude 主动调用
└── 例子：查询 GitHub、访问数据库

Hooks（自动化钩子）
├── 作用：定义 Claude "什么时候自动做"
├── 方向：事件 → 自动执行命令
├── 触发：事件自动触发
└── 例子：写完文件后自动格式化

8.6.2 详细对比表

对比维度	MCP	Hooks
核心功能	连接外部工具和数据	事件驱动的自动化
触发方式	Claude 主动调用	事件自动触发
配置方式	`mcpServers` 字段	`hooks` 字段
运行环境	MCP Server 进程	Shell 命令
交互方向	双向（请求和响应）	单向（执行命令）
典型用途	访问 GitHub、数据库、API	格式化、测试、通知
是否需要安装	需要安装 MCP Server	只需要 shell 命令

8.6.3 如何选择

需要让 Claude 获取外部信息或操作外部系统？
  → 使用 MCP
  → 例：查询数据库、操作 GitHub

需要在某个操作后自动执行固定步骤？
  → 使用 Hooks
  → 例：保存文件后自动格式化

两者可以同时使用，互不冲突！

8.7 动手实践

8.7.1 练习 1：配置自动格式化 Hook

目标：让 Claude 每次修改文件后自动运行 Prettier。

第 1 步：确认项目中有 Prettier

bash

# 检查是否安装了 Prettier
npx prettier --version
# 如果没有安装，先安装
npm install --save-dev prettier

第 2 步：创建或编辑项目配置文件

bash

# 确保 .claude 目录存在
mkdir -p .claude

编辑 .claude/settings.json：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path'); npx prettier --write \"$FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

第 3 步：测试

启动 Claude Code，让它创建一个格式不好的文件：

你：帮我创建一个 test.js 文件，内容是 const x=1;const y=2;console.log(x+y)，
全部写在一行

Claude：我来创建这个文件。
[创建 test.js]

观察结果——文件应该被自动格式化为：

javascript

const x = 1;
const y = 2;
console.log(x + y);

8.7.2 练习 2：配置变更日志 Hook

目标：记录 Claude 的所有文件修改操作。

编辑 .claude/settings.json：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "INPUT=$(cat /dev/stdin); TOOL=$(echo $INPUT | jq -r '.tool_name'); FILE_PATH=$(echo $INPUT | jq -r '.tool_input.file_path'); echo \"$(date '+%Y-%m-%d %H:%M:%S') [$TOOL] $FILE_PATH\" >> .claude/change-log.txt"
          }
        ]
      }
    ]
  }
}

让 Claude 做一些文件修改操作，然后查看日志：

bash

cat .claude/change-log.txt
# 输出示例：
# 2024-01-15 14:32:15 [Write] src/index.js
# 2024-01-15 14:32:45 [Edit] src/styles.css
# 2024-01-15 14:33:10 [Write] README.md

8.7.3 练习 3：配置安全防护 Hook

目标：阻止 Claude 修改敏感配置文件。

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path'); if echo \"$FILE_PATH\" | grep -qE '(\\.env|\\.secret|credentials|password)'; then echo 'BLOCKED: 不允许修改敏感文件' >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

测试：

你：帮我在 .env 文件中添加一行 API_KEY=test123

Claude：抱歉，修改 .env 文件的操作被 Hook 拦截了。
根据项目安全配置，我无法修改敏感文件（如 .env、.secret 等）。
请手动修改这些文件。

8.8 Hooks 最佳实践

8.8.1 命令设计原则

1. 【快速执行】
   Hook 命令应该快速完成，避免耗时操作
   ✅ npx prettier --write file.js    （秒级完成）
   ❌ npm run build                    （可能需要几分钟）

2. 【容错处理】
   始终添加错误处理，避免 Hook 失败影响 Claude
   ✅ command ... 2>/dev/null || true
   ❌ command ...  （失败会导致问题）

3. 【条件过滤】
   只对相关文件执行操作
   ✅ 检查文件扩展名后再运行 linter
   ❌ 对所有文件都运行 linter

4. 【幂等性】
   命令执行多次应该得到相同结果
   ✅ prettier --write（多次格式化结果一样）
   ✅ git add file（多次添加没有副作用）

8.8.2 性能考虑

避免 Hook 成为性能瓶颈

每次 Claude 调用工具都会触发 Hook，如果 Hook 太慢会严重影响体验
建议 Hook 命令在 1-2 秒内完成
避免在 PostToolUse 中运行完整的测试套件
如果需要运行耗时操作，考虑放在 Stop 事件中（只执行一次）

8.8.3 调试 Hooks

如果 Hook 没有按预期工作：

bash

# 1. 检查配置文件格式是否正确
cat .claude/settings.json | python -m json.tool

# 2. 手动测试命令（模拟 stdin JSON）
echo '{"tool_name":"Write","tool_input":{"file_path":"test.js"}}' | bash -c 'FILE_PATH=$(cat /dev/stdin | jq -r ".tool_input.file_path"); npx prettier --write "$FILE_PATH"'

# 3. 检查命令是否存在
which prettier
which eslint

# 4. 查看 Claude Code 的日志输出
# 当 Hook 执行失败时，Claude Code 通常会在对话中显示错误信息

8.9 进阶：组合 Hooks 与 MCP

Hooks 和 MCP 可以配合使用，形成强大的自动化工作流：

8.9.1 场景示例

配置：
- MCP: GitHub Server（让 Claude 能操作 GitHub）
- Hook: Stop 事件发送 Slack 通知

工作流：
1. 你让 Claude 帮你创建一个 GitHub Issue
2. Claude 通过 MCP 调用 GitHub Server 创建 Issue
3. 任务完成后，Stop Hook 自动发送 Slack 通知
4. 你的团队在 Slack 中收到通知

8.9.2 完整的协作配置

json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE_PATH=$(cat /dev/stdin | jq -r '.tool_input.file_path'); npx prettier --write \"$FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): Claude Code 任务完成\" >> ~/.claude/activity.log"
          }
        ]
      }
    ]
  }
}

8.10 常见问题

8.10.1 Hook 命令失败会怎样？

PostToolUse / Stop / Notification：命令失败不会影响 Claude 继续工作，但你可能会看到错误输出
PreToolUse：命令返回退出码 2 会阻止工具执行，用于实现安全拦截；退出码 1 仅产生一条警告但不会阻止工具执行；退出码 0 表示正常放行

8.10.2 多个 Hook 的执行顺序

如果同一个事件配置了多个 Hook：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          { "type": "command", "command": "echo 'first'" },
          { "type": "command", "command": "echo 'second'" },
          { "type": "command", "command": "echo 'third'" }
        ]
      }
    ]
  }
}

它们会按照在数组中的顺序依次执行：first -> second -> third。

8.10.3 Hook 命令可以访问什么？

Hook 命令在你当前项目目录下执行，它可以：

通过 stdin 读取事件的 JSON 数据（使用 jq 解析）
访问 CLAUDE_PROJECT_DIR 和 CLAUDE_CODE_ENTRYPOINT 环境变量
访问项目中的所有文件
使用系统中安装的任何命令行工具
执行 npm/npx 命令

8.11 本章小结

在本章中，我们学习了：

Hooks 的概念 —— 事件驱动的自动化机制
事件类型 —— PreToolUse、PostToolUse、Stop、Notification、UserPromptSubmit、SessionStart 等
配置方法 —— 在 settings.json 的 hooks 字段中配置
实用场景 —— 自动格式化、自动测试、通知、日志记录、安全拦截
与 MCP 的区别 —— MCP 扩展能力，Hooks 自动化流程
最佳实践 —— 快速执行、容错处理、条件过滤

下一步

在下一章中，我们将学习 权限与安全，深入了解如何控制 Claude Code 的权限级别，保护你的项目和数据安全。权限系统和 Hooks 的安全拦截功能是互补的——权限系统控制"Claude 能做什么"，Hooks 拦截可以实现更细粒度的"哪些具体操作不允许"。

第 8 章：Hooks（自动化钩子） ​

本章概览 ​

8.1什么是 Hooks？ ​

8.1.1一个类比 ​

8.1.2正式定义 ​

8.1.3Hooks vs 在 CLAUDE.md 中写规则 ​

8.2Hooks 事件类型 ​

8.2.1支持的事件 ​

8.2.2事件流程图 ​

8.2.3PreToolUse 详解 ​

8.2.4PostToolUse 详解 ​

8.2.5Stop 详解 ​

8.3 配置 Hooks ​

8.3.1 配置文件位置 ​

8.3.2 配置格式 ​

8.3.3 配置字段详解 ​

8.3.4 Hook 命令如何获取事件数据 ​

8.4 实用 Hooks 示例 ​

8.4.1 示例 1：自动代码格式化 ​

8.4.2 示例 2：自动运行 ESLint 检查 ​

8.4.3 示例 3：自动运行测试 ​

8.4.4 示例 4：任务完成通知 ​

8.4.5 示例 5：变更日志记录 ​

8.4.6 示例 6：Git 自动暂存 ​

8.4.7 示例 7：PreToolUse 拦截示例 ​

8.5 完整的项目配置示例 ​

8.6 Hooks 与 MCP 的区别 ​

8.6.1 概念对比 ​

8.6.2 详细对比表 ​

8.6.3 如何选择 ​

8.7 动手实践 ​

8.7.1 练习 1：配置自动格式化 Hook ​

8.7.2 练习 2：配置变更日志 Hook ​

8.7.3 练习 3：配置安全防护 Hook ​

8.8 Hooks 最佳实践 ​

8.8.1 命令设计原则 ​

8.8.2 性能考虑 ​

8.8.3 调试 Hooks ​

8.9 进阶：组合 Hooks 与 MCP ​

8.9.1 场景示例 ​

8.9.2 完整的协作配置 ​

8.10 常见问题 ​

8.10.1 Hook 命令失败会怎样？ ​

8.10.2 多个 Hook 的执行顺序 ​

8.10.3 Hook 命令可以访问什么？ ​

8.11 本章小结 ​

第 8 章：Hooks（自动化钩子）

本章概览

8.1什么是 Hooks？

8.1.1一个类比

8.1.2正式定义

8.1.3Hooks vs 在 CLAUDE.md 中写规则

8.2Hooks 事件类型

8.2.1支持的事件

8.2.2事件流程图

8.2.3PreToolUse 详解

8.2.4PostToolUse 详解

8.2.5Stop 详解

8.3 配置 Hooks

8.3.1 配置文件位置

8.3.2 配置格式

8.3.3 配置字段详解

8.3.4 Hook 命令如何获取事件数据

8.4 实用 Hooks 示例

8.4.1 示例 1：自动代码格式化

8.4.2 示例 2：自动运行 ESLint 检查

8.4.3 示例 3：自动运行测试

8.4.4 示例 4：任务完成通知

8.4.5 示例 5：变更日志记录

8.4.6 示例 6：Git 自动暂存

8.4.7 示例 7：PreToolUse 拦截示例

8.5 完整的项目配置示例

8.6 Hooks 与 MCP 的区别

8.6.1 概念对比

8.6.2 详细对比表

8.6.3 如何选择

8.7 动手实践

8.7.1 练习 1：配置自动格式化 Hook

8.7.2 练习 2：配置变更日志 Hook

8.7.3 练习 3：配置安全防护 Hook

8.8 Hooks 最佳实践

8.8.1 命令设计原则

8.8.2 性能考虑

8.8.3 调试 Hooks

8.9 进阶：组合 Hooks 与 MCP

8.9.1 场景示例

8.9.2 完整的协作配置

8.10 常见问题

8.10.1 Hook 命令失败会怎样？

8.10.2 多个 Hook 的执行顺序

8.10.3 Hook 命令可以访问什么？

8.11 本章小结