【claude code实践】Hooks 使用场景：格式化、测试、扫描与提醒-拓冰网站定制

1. 为什么 Claude Code 需要 Hooks：从“AI 说它跑过了”到“真的跑过了”

如果你用 Claude Code 写过一段时间代码，大概率遇到过这种场景：让它改完一个函数，它回复“已完成，测试通过”，但你手动跑一遍npm test，红的。或者它生成的代码风格和项目里 Prettier 配置完全对不上，缩进两格变四格，单引号变双引号。再或者，它在你没注意的时候往代码里塞了一个console.log，提交上去被同事在 Review 里圈出来。

这些问题的根源不是 Claude Code 不会写代码，而是它缺少一个“在正确时机自动执行正确动作”的机制。Hooks 就是补上这一环的东西。它让你在 Claude Code 的工作流里插入检查点：文件保存时自动格式化、提交前自动跑测试、代码里出现敏感词时自动扫描、任务完成时自动提醒。你不需要每次手动敲命令，也不需要反复在对话里提醒它“记得跑测试”——Hooks 会在事件触发时自动执行。

这篇文章围绕四个真实场景展开：保存即格式化、提交前跑测试、敏感词扫描、任务完成提醒。每个场景我都会给出settings.json里的配置骨架、TaoToken 统一 Key/API 通道的接入方式，以及逐条验证动作。你跟着配完，每条 Hook 都能复现生效。

2. TaoToken 前置：统一 Key 与 API 通道

在配置 Hooks 之前，先把模型调用通道理清楚。Claude Code 本身是一个客户端工具，它需要连接到一个兼容 Anthropic API 的服务端点。TaoToken 提供的就是这个通道：一个统一的 Key，一个统一的 API 地址，让你在 Claude Code、Coding Plan、模型对话等多个入口之间不用反复切换配置。

你需要准备的东西很简单：

一个 TaoToken 账号，登录后进入控制台
在 API Keys 页面生成一个 Key，复制保存
确认 API 端点地址为https://taotoken.net/api

配置方式有两种。第一种是环境变量，适合在终端里直接跑 Claude Code 的场景：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="你的TaoToken Key"

第二种是写进 Claude Code 的配置文件，适合长期使用。配置文件通常位于~/.claude/settings.json或项目根目录的.claude/settings.json。Hooks 的配置也写在这个文件里，所以后面我们会把 Key 配置和 Hooks 配置放在同一个文件中管理。

注意：API 地址不要加 UTM 参数，直接使用https://taotoken.net/api即可。控制台和 API Keys 页面在配置过程中会用到，建议提前打开。

如果你还没有 Key，可以先去控制台创建。整个流程不需要额外安装任何东西，Claude Code 本身通过 npm 安装后就能用。

3. 可复制配置：settings.json 中的 Hooks 骨架

Claude Code 的 Hooks 配置写在settings.json的hooks字段里。每个 Hook 由三部分组成：触发事件（event）、匹配条件（matcher）、执行命令（command）。下面是一个完整的配置骨架，包含四个场景的 Hook 定义。

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "你的TaoToken Key" }, "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] } ], "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "echo \"[Hook] 即将执行命令: $CLAUDE_TOOL_INPUT\" >> .claude/hook-audit.log" } ] } ], "Stop": [ { "matcher": "", "hooks": [ { "type": "command", "command": "bash .claude/hooks/on-stop.sh" } ] } ] } }

这个骨架里包含了三个事件类型：PostToolUse在工具调用完成后触发，适合做格式化和扫描；PreToolUse在工具调用前触发，适合做审计和拦截；Stop在 Claude Code 完成一轮任务后触发，适合做提醒和汇总。

3.1 保存即格式化：PostToolUse + Prettier

第一个场景是文件保存后自动格式化。Claude Code 在写入或编辑文件后会触发PostToolUse事件，我们在这个事件上挂一个 Prettier 命令。

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

这里的$CLAUDE_FILE_PATH是 Claude Code 传入的环境变量，指向被修改的文件路径。matcher字段用正则匹配工具名称，Write|Edit表示文件写入和编辑操作都会触发。|| true的作用是即使 Prettier 报错也不阻断后续流程，避免因为格式化工具本身的问题导致 Claude Code 卡住。

如果你用的是 Python 项目，把命令换成black或ruff format即可：

{ "command": "ruff format \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" }

3.2 提交前跑测试：PreToolUse + 测试命令

第二个场景是在 Claude Code 执行git commit之前自动跑测试。这里用PreToolUse事件匹配Bash工具，然后检查命令内容是否包含git commit。

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'git commit'; then npm test -- --passWithNoTests 2>&1 | tail -20; fi" } ] } ] } }

这段命令的逻辑是：如果 Claude Code 准备执行的 Bash 命令里包含git commit，就先跑npm test，并把最后 20 行输出打印出来。如果测试失败，输出会显示在 Claude Code 的对话里，你可以根据结果决定是否继续提交。

注意：这个 Hook 不会自动阻断提交，它只是把测试结果展示出来。如果你希望测试失败时直接阻止提交，可以把命令改成npm test || exit 1，这样非零退出码会中断后续操作。

3.3 敏感词扫描：PostToolUse + grep 检查

第三个场景是扫描代码中是否出现了不该出现的敏感词，比如硬编码的密钥、调试用的console.log、或者团队约定的禁用 API。

{ "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "grep -nE '(API_KEY|SECRET|password|console\\.log)' \"$CLAUDE_FILE_PATH\" && echo '[警告] 发现敏感词，请检查' || true" } ] } ] } }

这个命令会在文件被修改后立即扫描，如果匹配到敏感词就打印行号和警告信息。grep的-n参数显示行号，-E启用扩展正则。匹配到内容时grep返回 0，&&后面的 echo 会执行；没匹配到时grep返回非零，|| true保证整体退出码为 0，不阻断流程。

你可以根据项目需要调整正则表达式。比如加上TODO|FIXME来追踪待办事项，或者加上内部域名、测试账号等。

3.4 任务完成提醒：Stop + 自定义脚本

第四个场景是 Claude Code 完成一轮任务后发送提醒。Stop事件在 Claude Code 结束当前回合时触发，适合做汇总通知。

先创建一个脚本文件.claude/hooks/on-stop.sh：

#!/bin/bash TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S') echo "[$TIMESTAMP] Claude Code 任务完成" >> .claude/hook-audit.log if command -v notify-send &> /dev/null; then notify-send "Claude Code" "任务已完成，请检查变更" fi

然后在settings.json里挂上这个脚本：

{ "hooks": { "Stop": [ { "matcher": "", "hooks": [ { "type": "command", "command": "bash .claude/hooks/on-stop.sh" } ] } ] } }

matcher为空字符串表示匹配所有 Stop 事件。脚本里做了两件事：写审计日志、发送桌面通知（如果系统支持notify-send）。如果你在 macOS 上，可以把通知命令换成osascript -e 'display notification "任务已完成" with title "Claude Code"'。

4. 验证请求与成功结果

配置写完后，需要逐条验证 Hook 是否真的生效。下面是我实际跑过的验证步骤和预期结果。

4.1 验证格式化 Hook

在项目里创建一个测试文件，故意写成不符合 Prettier 规范的格式：

const x=1;const y =2 function test( ){return x+y}

然后在 Claude Code 里让它编辑这个文件，比如“把 test 函数的返回值改成 x*y”。编辑完成后，打开文件检查格式是否被自动修正。如果 Prettier 生效，你会看到代码变成了：

const x = 1; const y = 2; function test() { return x * y; }

如果格式没变，检查settings.json里的路径是否正确，以及npx prettier是否能在项目根目录下正常运行。

4.2 验证测试 Hook

在 Claude Code 里输入“帮我提交当前变更”，它会尝试执行git commit。此时观察对话输出，应该能看到npm test的运行结果。如果测试通过，输出里会有绿色的 PASS 行；如果失败，会显示具体的失败用例。

你也可以手动触发验证：在 Claude Code 里执行git commit -m "test"，看 Hook 是否拦截并展示测试输出。

4.3 验证扫描 Hook

创建一个包含敏感词的文件：

const API_KEY = "sk-test-123"; console.log("debug");

让 Claude Code 编辑这个文件，保存后观察对话里是否出现[警告] 发现敏感词以及对应的行号。如果没出现，检查grep命令里的正则是否匹配到了你的测试内容。

4.4 验证提醒 Hook

让 Claude Code 完成一个简单任务，比如“在当前目录创建一个 hello.txt 文件”。任务结束后，检查.claude/hook-audit.log是否多了一行时间戳记录。如果系统支持桌面通知，还应该看到弹窗。

5. 本篇常见错排查

配置 Hooks 的过程中，有几个坑我踩过，这里列出来帮你省时间。

Hook 不触发：最常见的原因是settings.json的路径不对。Claude Code 会读取项目根目录的.claude/settings.json和用户目录的~/.claude/settings.json，两个文件会合并。如果你改的是项目里的文件但没生效，检查一下是不是被用户目录的配置覆盖了。

环境变量为空：$CLAUDE_FILE_PATH和$CLAUDE_TOOL_INPUT是 Claude Code 注入的变量，不是系统环境变量。如果你在脚本里直接echo $CLAUDE_FILE_PATH发现是空的，说明当前事件类型不提供这个变量。比如Stop事件就没有文件路径，只有PostToolUse和PreToolUse才有。

命令执行超时：Hooks 默认有超时限制，如果npm test跑太久会被中断。建议在 Hook 里只跑快速测试，比如npm test -- --testPathPattern=changed或者用--bail参数让测试在第一个失败时停止。

Prettier 找不到配置文件：如果项目里的 Prettier 配置在子目录，npx prettier可能读不到。可以在命令里显式指定配置路径：npx prettier --config .prettierrc --write "$CLAUDE_FILE_PATH"。

Hook 输出太多刷屏：npm test的完整输出可能很长，建议用tail -20或head -30截断。我在配置里用了tail -20，只展示最后 20 行，足够判断测试是否通过。

Windows 环境兼容性：上面的命令都是 bash 语法，在 Windows 的 CMD 或 PowerShell 里需要调整。建议在 Windows 上使用 Git Bash 或 WSL 来运行 Claude Code，这样 Hook 命令可以直接复用。

6. 把 Hooks 接入你的日常流程

四个场景配下来，你会发现 Hooks 的核心价值不是“自动化”本身，而是把那些“理应发生但容易被遗忘”的检查变成了默认行为。格式化、测试、扫描、提醒，这四件事单独看都不复杂，但每次手动执行都会消耗注意力。Hooks 把它们从待办清单里移除，让你专注于代码逻辑本身。

如果你还没有配置 TaoToken 的 API 通道，建议先去控制台创建一个 Key，然后把settings.json里的env字段填好。模型对话入口可以用来快速验证 Key 是否有效，Coding Plan 适合长期编码场景，接入文档里有更详细的参数说明。配置完成后，从格式化 Hook 开始逐条验证，确认每条都生效后再逐步加上测试和扫描。不要一次性全开，否则出问题时排查起来会很麻烦。

最后提醒一点：Hooks 是辅助机制，不是替代品。它不能替你判断代码逻辑是否正确，也不能替代 Code Review。它的作用是确保你提交的代码在格式、测试、安全扫描这些可程序化定义的维度上，始终处于可控状态。把规则定义清楚，让系统自动执行，你只需要在关键节点做决策。

资讯详情

【claude code实践】Hooks 使用场景：格式化、测试、扫描与提醒