Claude Code Hooks 完全指南：自动格式化、自动测试等实用配置

什么是 Hooks？

Claude Code Hooks 允许你在特定操作前后自动执行自定义命令。你可以设置在文件保存后自动格式化、代码修改后自动运行测试等功能。

Hooks 在 .claude/settings.json 中定义，当 Claude Code 执行特定操作时会触发对应的 Shell 命令。

Hook 类型

Claude Code 支持以下事件触发点的 Hooks：

Hook 事件	触发时机
PreToolUse	工具执行前
PostToolUse	工具执行后
Notification	发送通知时
Stop	Claude Code 完成响应时

基本配置

Hooks 在 .claude/settings.json 的 hooks 字段中定义：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

配置结构

• matcher：用于匹配触发工具名称的正则表达式
• command：要执行的 Shell 命令

场景 1：自动格式化

文件编辑后自动运行 Prettier：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

配置完成后，每当 Claude Code 创建或编辑文件时，Prettier 都会自动进行格式化。无需手动操作，团队的代码风格就能保持一致。

场景 2：自动 Lint 检查

集成 ESLint 自动修复：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}

末尾的 || true 可以防止 lint 错误导致 Hook 执行失败，确保 Claude Code 能继续处理后续操作。

场景 3：代码变更后自动测试

文件编辑后自动运行相关测试并反馈结果：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx vitest related \"$CLAUDE_FILE_PATH\" --run 2>&1 | tail -20"
      }
    ]
  }
}

Vitest 的 related 选项只会运行与修改文件相关的测试，比完整测试套件快得多。

场景 4：自动类型检查

文件变更后运行 TypeScript 类型检查：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx tsc --noEmit 2>&1 | head -30"
      }
    ]
  }
}

场景 5：拦截危险命令

通过 PreToolUse Hook 阻止高风险命令的执行：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|drop table|git push.*force'; then echo 'BLOCKED: Dangerous command detected' >&2; exit 1; fi"
      }
    ]
  }
}

当 Hook 以退出码 1 结束时，Claude Code 会跳过该工具的执行。

场景 6：完成通知

当 Claude Code 完成任务时发送通知：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "command": "notify-send 'Claude Code' 'Task completed' 2>/dev/null; echo 'Done'"
      }
    ]
  }
}

macOS 上可以使用：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "command": "osascript -e 'display notification \"Task completed\" with title \"Claude Code\"'"
      }
    ]
  }
}

组合多个 Hooks

在实际项目中，组合使用多个 Hooks 效果最佳：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf /'; then exit 1; fi"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      },
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "command": "echo '✓ Task completed'"
      }
    ]
  }
}

Hooks 编写技巧

1. 保持执行时间短

Hooks 是同步执行的，耗时操作会拖慢 Claude Code 的响应速度。使用 related 缩小测试范围，用 head 或 tail 截断输出。

2. 优雅地处理错误

Hook 执行出错可能会中断 Claude Code 的工作流。使用 || true 和 2>/dev/null 确保安全。

3. 善用环境变量

充分利用 Hooks 中可用的环境变量。$CLAUDE_FILE_PATH 可以获取正在操作的文件路径。

总结

Hooks 让你可以深度定制 Claude Code 的工作流。自动格式化加自动测试的组合在维护代码质量方面尤其强大。先从 Prettier 自动格式化开始，然后逐步扩展。