Claude Code Hooks 完全指南

掌握 Claude Code 自动化工作流的核心机制

核心机制: 事件驱动的自动化响应 | 配置方式: JSON + Shell 命令 | 应用场景: 代码质量、安全防护、工作流自动化

🎯 什么是 Claude Code Hooks?

Claude Code Hooks 是在系统生命周期特定时刻自动执行的 Shell 命令,让你能够验证、修改或阻止工具调用,验证用户输入,以及管理会话生命周期事件。

核心价值

正在加载图表...

Hooks vs LLM 决策

为什么使用 Hooks 而非依赖 LLM?

⚡ 确定性: Shell 命令提供可预测的结果,LLM 可能产生不一致的输出
🔒 安全性: 通过 exit code 明确控制是否允许操作,无需”希望” LLM 理解
🚀 性能: 直接执行 Shell 命令比多轮 LLM 对话快得多
💰 成本: 避免额外的 LLM API 调用

设计哲学: “对于需要确定性的任务,使用 Hooks;对于需要智能判断的任务,依赖 LLM”

🏗️ Claude Code Hooks 系统架构

整体架构图

正在加载图表...

📋 Hook 事件类型详解

9 种 Hook 事件

1. PreToolUse - 工具执行前

触发时机: 在任何工具(Read, Write, Edit, Bash 等)执行之前

典型用例:

🔒 阻止编辑敏感文件 (.env, credentials.json)
🛡️ 防止路径遍历攻击
✅ 验证文件路径合法性
📝 记录工具调用日志

特性: 可以通过 exit code 2 阻止工具执行

2. PostToolUse - 工具执行后

触发时机: 工具成功执行后

典型用例:

🎨 自动运行代码格式化工具 (Prettier, Black)
📦 整理导入语句 (organize imports)
🔧 运行 linter (ESLint, Ruff)
📊 生成代码统计

特性: 无法阻止已完成的操作,但可以修改输出或触发后续操作

3. UserPromptSubmit - 用户提交提示词

触发时机: 用户提交消息之前

典型用例:

📝 验证用户输入格式
🔍 丰富提示词上下文
🚫 过滤敏感信息
📋 强制包含特定指令

特性: 可以修改或阻止用户提示词

4. Notification - 系统通知

触发时机: Claude 发送通知时

典型用例:

🔔 自定义桌面通知
📧 发送邮件/Slack 通知
📱 集成第三方通知服务
🎵 播放声音提示

特性: 增强用户体验,提供自定义反馈

5. Stop - 代理停止响应

触发时机: Claude 完成响应并停止之前

典型用例:

✅ 运行完整的质量检查套件
🧪 执行测试套件
📦 运行构建流程
📊 生成会话摘要

特性: 最重要的 Hook 事件,用于端到端质量门控

6. SubagentStop - 子代理停止

触发时机: 子代理(Task 工具启动的代理)完成任务之前

典型用例:

🎯 验证子任务完成质量
📋 收集子任务执行报告
🔄 决定是否重新执行子任务

特性: 支持 Prompt Hook,可以使用 LLM 智能决策

7. PreCompact - 上下文压缩前

触发时机: Claude 准备压缩对话上下文之前

典型用例:

💾 保存重要上下文到文件
📝 生成会话快照
🗃️ 归档关键信息

特性: 防止重要信息在上下文压缩中丢失

8. SessionStart - 会话开始

触发时机: 新会话启动或恢复会话时

典型用例:

📋 加载项目上下文 (git status, 最近的 issue)
🔧 初始化开发环境
📊 显示项目状态
🎯 设置会话目标

特性: 自动化会话初始化流程

9. SessionEnd - 会话结束

触发时机: 会话即将结束时

典型用例:

💾 保存会话状态
📊 生成会话报告
🧹 清理临时文件
📧 发送完成通知

特性: 会话清理和总结

⚙️ Hook 类型与配置

两种 Hook 类型

正在加载图表...

配置文件层级

正在加载图表...

📝 配置格式与示例

基础配置结构

{
"hooks": {
  "事件名称": [
    {
      "matcher": "工具名称或文件模式",

点击展开查看完整代码共 15 行

Matcher 系统详解

正在加载图表...

🚀 实战示例

示例 1: 自动代码格式化

{
"hooks": {
  "PostToolUse": [
    {
      "matcher": "Edit|Write",

点击展开查看完整代码共 15 行

工作流程:

正在加载图表...

示例 2: 敏感文件保护

{
"hooks": {
  "PreToolUse": [
    {
      "matcher": "Edit|Write",

点击展开查看完整代码共 15 行

安全防护流程:

正在加载图表...

示例 3: Stop Hook - 质量门控

{
"hooks": {
  "Stop": [
    {
      "hooks": [

点击展开查看完整代码共 14 行

质量检查流程:

正在加载图表...

示例 4: 自定义通知

{
"hooks": {
  "Notification": [
    {
      "hooks": [

点击展开查看完整代码共 14 行

示例 5: SessionStart - 加载上下文

{
"hooks": {
  "SessionStart": [
    {
      "hooks": [

点击展开查看完整代码共 14 行

示例 6: 多 Hook 组合

{
"hooks": {
  "PreToolUse": [
    {
      "matcher": "Edit|Write",
      "hooks": [
        {
          "type": "command",
          "command": "bash -c 'for file in $CLAUDE_FILE_PATHS; do case \"$file\" in *.env|*.secret) echo \"❌ 禁止编辑: $file\" >&2; exit 2;; esac; done'"
        }
      ]
    },
    {
      "matcher": "Bash:rm *",
      "hooks": [

点击展开查看完整代码共 82 行

🔌 Hook 输入输出协议

标准输入 (stdin) - JSON 格式

Hook 通过 stdin 接收 JSON 格式的上下文信息:

{
"event": "PostToolUse",
"tool": "Edit",
"sessionId": "abc123",
"workingDirectory": "/Users/you/project",

点击展开查看完整代码共 11 行

环境变量

Hook 可以访问以下环境变量:

$CLAUDE_FILE_PATHS - 受影响文件的路径列表(空格分隔)
$CLAUDE_TOOL_NAME - 被调用的工具名称
$CLAUDE_SESSION_ID - 当前会话 ID
$CLAUDE_WORKING_DIR - 工作目录
$CLAUDE_NOTIFICATION_MESSAGE - 通知消息内容

退出码 (Exit Code)

正在加载图表...

标准输出 (stdout) - 高级控制

{
"action": "block",
"message": "❌ 代码格式化失败: 发现 3 个错误",
"details": {
  "errors": [

点击展开查看完整代码共 15 行

🛡️ 安全最佳实践

⚠️ 安全警告

Claude Code hooks 在你的系统上自动执行任意 shell 命令,具有你当前环境的凭据。

恶意的 hooks 代码可能:

📤 泄露你的数据
🗑️ 删除文件
🔓 访问私密信息
💻 执行未授权操作

防护措施: 始终在启用 hooks 之前审查实现代码!

6 大安全检查项

正在加载图表...

安全配置示例

#!/bin/bash
# ✅ 安全的 Hook 脚本示例

# 1. 引用所有变量
for file in $CLAUDE_FILE_PATHS; do

点击展开查看完整代码共 32 行

常见安全陷阱

# ❌ 危险: 未引用变量
prettier --write $CLAUDE_FILE_PATHS
# 问题: 如果文件名包含空格,会被分词

# ✅ 安全: 正确引用

点击展开查看完整代码共 28 行

📈 性能优化建议

Hook 性能影响分析

正在加载图表...

性能优化建议

1. PostToolUse Hook - 保持快速

推荐: < 1 秒

✅ 代码格式化 (Prettier, Black)
✅ 导入排序 (organize imports)
✅ 轻量级 Linting (ESLint —fix)

避免:

❌ 完整测试套件
❌ 重型类型检查
❌ 包安装

2. Stop Hook - 深度检查

允许: 几秒到几分钟

✅ 完整 Lint (ESLint, Ruff)
✅ 类型检查 (TypeScript, mypy)
✅ 测试运行 (Jest, pytest)
✅ 构建验证 (npm run build)

优化技巧:

使用缓存加速重复检查
并行运行独立检查
提供进度反馈

性能优化示例

{
"hooks": {
  "Stop": [
    {
      "hooks": [

点击展开查看完整代码共 14 行

🎓 高级技巧与模式

技巧 1: 条件执行

#!/bin/bash
# 只在 CI 环境运行完整检查

if [ "$CI" = "true" ]; then
echo "🤖 CI 环境 - 运行完整检查"

点击展开查看完整代码共 10 行

技巧 2: 增量检查

#!/bin/bash
# 增量 Linting - 只检查修改的文件

if [ -n "$CLAUDE_FILE_PATHS" ]; then
echo "🔍 检查修改的文件..."

点击展开查看完整代码共 10 行

技巧 3: 自定义日志

#!/bin/bash
# 记录所有 Hook 执行到日志文件

LOG_FILE=".claude/hooks.log"
TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')

点击展开查看完整代码共 22 行

技巧 4: 交互式确认

#!/bin/bash
# 删除文件前要求确认

if [[ "$CLAUDE_TOOL_NAME" == "Bash" && "$CLAUDE_COMMAND" == *"rm"* ]]; then
echo "⚠️  检测到删除操作: $CLAUDE_COMMAND"

点击展开查看完整代码共 14 行

技巧 5: Hook 链

{
"hooks": {
  "PostToolUse": [
    {
      "matcher": "Edit|Write:*.ts|*.tsx",

点击展开查看完整代码共 23 行

🔧 调试 Hooks

调试工作流

正在加载图表...

调试技巧

#!/bin/bash
# 调试模式 - 输出所有环境信息

DEBUG=true

点击展开查看完整代码共 26 行

常见问题排查

问题 1: Hook 没有触发

✅ 检查 Matcher 是否正确匹配工具/文件
✅ 确认配置文件位置正确
✅ 验证 JSON 语法无误
✅ 重启 Claude Code

问题 2: Hook 执行失败

✅ 检查 Shell 命令是否正确
✅ 验证文件路径是否存在
✅ 确认工具已安装 (prettier, eslint 等)
✅ 检查文件权限

问题 3: Hook 运行太慢

✅ 将重型检查移到 Stop Hook
✅ 使用增量检查
✅ 启用工具缓存
✅ 并行执行独立操作

问题 4: Hook 阻止了合法操作

✅ 调整 Matcher 范围
✅ 添加例外规则
✅ 改用 exit 1 (警告)而非 exit 2 (阻止)
✅ 提供更明确的错误信息

📚 真实案例研究

案例 1: TypeScript 项目自动化

{
"hooks": {
  "PreToolUse": [
    {
      "matcher": "Edit|Write",
      "hooks": [
        {
          "type": "command",
          "command": "bash -c 'for file in $CLAUDE_FILE_PATHS; do case \"$file\" in *.env*|*.secret*|package-lock.json) echo \"❌ 禁止编辑: $file\" >&2; exit 2;; esac; done'"
        }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "Edit|Write:*.ts|*.tsx",
      "hooks": [
        {
          "type": "command",
          "command": "prettier --write \"$CLAUDE_FILE_PATHS\""

点击展开查看完整代码共 59 行

案例 2: Python 项目自动化

{
"hooks": {
  "PostToolUse": [
    {
      "matcher": "Edit|Write:*.py",

点击展开查看完整代码共 42 行

案例 3: 多语言项目

{
"hooks": {
  "PostToolUse": [
    {
      "matcher": "Edit|Write:*.ts|*.tsx|*.js|*.jsx",
      "hooks": [
        {
          "type": "command",
          "command": "prettier --write \"$CLAUDE_FILE_PATHS\""
        }
      ]
    },
    {
      "matcher": "Edit|Write:*.py",
      "hooks": [

点击展开查看完整代码共 42 行

🚀 最佳实践总结

12 条黄金法则

正在加载图表...

Dos ✅ & Don’ts ❌

✅ 推荐做法

总是引用 Shell 变量
使用绝对路径执行工具
保持 PostToolUse Hook 快速
在 Stop Hook 做深度检查
提供清晰的错误信息
记录关键操作到日志
验证所有文件路径
使用 exit code 2 阻止危险操作
测试 Hook 的所有分支
文档化 Hook 配置

❌ 避免做法

未引用的 Shell 变量
在 PostToolUse 运行重型测试
使用 eval 执行动态命令
忽略退出码
不验证文件路径
直接操作敏感文件
过于复杂的 Hook 逻辑
没有错误处理
阻塞式的用户交互
忽略性能影响

📖 学习资源

官方文档

社区资源

技术博客

🏆 Claude Code Best Practices - Anthropic
🔨 How I Use Claude Code - Builder.io
📚 What is Claude Code Hooks - Apidog

🎯 快速开始指南

5 分钟上手

正在加载图表...

手动配置步骤

创建配置目录
```
mkdir -p .claude
```
创建配置文件
```
touch .claude/settings.json
```
添加基础配置

{
"hooks": {
  "PostToolUse": [
    {
      "matcher": "Edit|Write",

点击展开查看完整代码共 15 行

测试配置
- 编辑一个文件
- 观察 Prettier 是否自动运行
- 检查文件是否被格式化
逐步扩展
- 添加更多 Hook 事件
- 增加质量检查
- 配置团队规范

💡 总结

Claude Code Hooks 是自动化开发工作流的强大机制:

核心优势:

🎯 确定性 - Shell 命令提供可预测的结果
🔒 安全性 - 通过 exit code 明确控制操作
⚡ 性能 - 直接执行,无需 LLM 调用
🔧 灵活性 - 9 种事件类型覆盖完整生命周期

9 种 Hook 事件:

PreToolUse - 工具执行前(可阻止)
PostToolUse - 工具执行后(自动化)
UserPromptSubmit - 提示词提交前
Notification - 自定义通知
Stop - 端到端质量门控
SubagentStop - 子代理停止
PreCompact - 上下文压缩前
SessionStart - 会话开始
SessionEnd - 会话结束

两种 Hook 类型:

Command Hook - Shell 命令(快速、确定)
Prompt Hook - LLM 查询(智能、灵活)

三个配置层级:

用户级 - ~/.claude/settings.json
项目级 - .claude/settings.json
本地级 - .claude/settings.local.json

最佳实践:

始终引用 Shell 变量
PostToolUse 保持快速(< 1s)
Stop Hook 做深度检查
验证所有输入路径
提供清晰的错误信息

开始使用 Claude Code Hooks,自动化你的开发工作流! 🚀

Claude Code Hooks 完全指南

🎯 什么是 Claude Code Hooks?

核心价值

Hooks vs LLM 决策

🏗️ Claude Code Hooks 系统架构

整体架构图

📋 Hook 事件类型详解

9 种 Hook 事件

1. PreToolUse - 工具执行前

2. PostToolUse - 工具执行后

3. UserPromptSubmit - 用户提交提示词

4. Notification - 系统通知

5. Stop - 代理停止响应

6. SubagentStop - 子代理停止

7. PreCompact - 上下文压缩前

8. SessionStart - 会话开始

9. SessionEnd - 会话结束

⚙️ Hook 类型与配置

两种 Hook 类型

配置文件层级

📝 配置格式与示例

基础配置结构

Matcher 系统详解

🚀 实战示例

示例 1: 自动代码格式化

示例 2: 敏感文件保护

示例 3: Stop Hook - 质量门控

示例 4: 自定义通知

示例 5: SessionStart - 加载上下文

示例 6: 多 Hook 组合

🔌 Hook 输入输出协议

标准输入 (stdin) - JSON 格式

环境变量

退出码 (Exit Code)

标准输出 (stdout) - 高级控制

🛡️ 安全最佳实践

⚠️ 安全警告

6 大安全检查项

安全配置示例

常见安全陷阱

📈 性能优化建议

Hook 性能影响分析

性能优化建议

1. PostToolUse Hook - 保持快速

2. Stop Hook - 深度检查

性能优化示例

🎓 高级技巧与模式

技巧 1: 条件执行

技巧 2: 增量检查

技巧 3: 自定义日志

技巧 4: 交互式确认

技巧 5: Hook 链

🔧 调试 Hooks

调试工作流

调试技巧

常见问题排查

📚 真实案例研究

案例 1: TypeScript 项目自动化

案例 2: Python 项目自动化

案例 3: 多语言项目

🚀 最佳实践总结

12 条黄金法则

Dos ✅ & Don’ts ❌

✅ 推荐做法

❌ 避免做法

📖 学习资源

官方文档

社区资源

技术博客

🎯 快速开始指南

5 分钟上手

手动配置步骤

💡 总结

相关资源