加载中

钩子(Hooks)

第 12 课6 分钟
加载中

钩子(Hooks)

摘要文字记录

钩子(Hooks)让您可以在 Claude Code 生命周期的特定节点运行命令。 钩子与本课程中涵盖的其他内容之间的关键区别在于,钩子是确定性的——它们总是会运行。

为什么要使用钩子

您可以在 CLAUDE.md 中告诉 Claude 在每次文件编辑后运行 Prettier。大多数情况下它会这样做。但有时它不会。钩子能确保每一次都如此执行,没有例外。

常见用例包括:

  • 在文件编辑后自动格式化
  • 记录所有已执行的命令以满足合规要求
  • 阻止危险操作,例如修改生产文件
  • 在 Claude 完成任务时向自己发送通知

钩子的工作原理

钩子在您的 settings.json 中配置。您选择一个事件,可以选择性地为它适用的工具设置一个匹配器(matcher),并提供要运行的命令。一些最常见的事件包括:

  • PreToolUse —— 在工具调用之前运行
  • PostToolUse —— 在工具调用完成之后运行
  • UserPromptSubmit —— 在您提交提示、Claude 处理它之前运行
  • Stop —— 在 Claude 完成响应时运行
  • Notification —— 在 Claude 发送通知时运行

这些仅仅是您可以挂接的几种事件——Claude Code 支持更多事件。请参阅钩子参考获取完整列表。

您通过直接编辑 settings.json 来配置它们。Claude Code 内部的 /hooks 命令会打开一个只读的已配置钩子列表,方便您检查新添加的钩子是否已生效。

.claude 目录中带有钩子配置的 settings.json 文件

一个实际示例

最常见的钩子:在编辑后自动格式化。设置一个 PostToolUse 钩子,匹配器为 "Edit|Write",这样它就会在 Claude 使用 Edit 或 Write 工具后触发。该命令会运行您项目所使用的任何格式化工具。对于 Prettier,请将以下内容添加到 .claude/settings.json(它需要 jq):

json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "file=$(jq -r '.tool_input.file_path') && npx prettier --write -- \"$file\""
          }
        ]
      }
    ]
  }
}

要测试它,请让 Claude 编辑一个文件,然后检查该文件是否已被重新格式化。

使用 PreToolUse 进行阻止

PreToolUse 钩子可以在工具调用执行之前阻止该调用。您的钩子会在标准输入(stdin)上以 JSON 格式接收工具名称和输入。退出代码决定了具体行为:

  • 退出代码 0 —— 正常继续。
  • 退出代码 2 —— 阻止该操作。stderr 消息会被反馈给 Claude,让它知道被阻止的原因,以便进行调整。
  • 其他任何退出代码 —— 一个非阻塞性错误,会显示给您看,但不会阻止任何操作。

这就是您强制执行硬性规则的方式。阻止对生产配置目录的写入。阻止包含 rm -rf 的 bash 命令。阻止对 main 分支的提交。无论您的团队需要什么被确保执行,而不仅仅是建议执行。

一个显示带有匹配器和命令的 PreToolUse 和 PostToolUse 钩子的 settings.json 文件

与团队共享钩子

在 .claude/settings.json 中配置的钩子属于项目级别,可以提交到您的代码仓库中。这意味着您的整个团队会自动获得相同的钩子。在您的命令中使用 CLAUDE_PROJECT_DIR 环境变量来引用存储在项目中的脚本,这样无论 Claude 当前的工作目录是什么,它们都能正常工作。

回顾

钩子让您能够对 Claude Code 的行为进行确定性控制。使用 PostToolUse 来自动格式化和记录日志。使用 PreToolUse 来阻止危险操作。在 settings.json 中配置它们,并用 /hooks 查看它们。并将它们提交到您的代码仓库,让您的团队也能获得这些钩子。

如果某件事需要每次都毫无失误地发生,不要把它放在提示中。把它放进钩子里。