Claude Code Hooks 完全指南：五大触发时机与实战配置详解

什么是 Claude Code Hooks

在日常使用 Claude Code 进行开发时，你是否注意到大量重复性操作正在吞噬你的时间？写代码前要初始化环境，改完代码要检查格式，提交前还要跑一遍测试流程……这些机械性的动作，其实完全可以交给 AI 自动完成。

Hooks 本质上是一种自动触发机制。你只需要配置一次，Claude Code 就能在特定时机帮你自动完成一系列预设动作。它的核心价值在于：将所有重复操作全部自动化，让你把精力集中在真正的业务逻辑上。

Hook（钩子）是软件工程中一个历史悠久的设计模式，最早可追溯到操作系统层面的中断处理机制。在现代开发中，Git Hooks（如 pre-commit、post-merge）、React Hooks（如 useState、useEffect）、Webpack Plugin Hooks 等都是这一理念的具体实现。其核心思想是在程序执行的关键节点插入自定义逻辑，实现对流程的非侵入式扩展。Claude Code Hooks 延续了这一设计哲学，将 Hook 机制引入 AI 辅助编程场景，让开发者能够在 AI 执行操作的生命周期中插入自定义的控制逻辑。

Hooks 的五大触发时机

在 Claude Code 中输入 /hooks 命令，会出现五个触发选项，分别对应不同的使用场景：

1. PreToolUse — 工具执行前触发

这是最常用的 Hook 类型之一。在 Claude 执行任何工具操作之前触发，适合用来做安全检查、参数校验等前置拦截。比如在删除文件前弹出确认提示，防止误操作。

PreToolUse 的设计本质上是一种拦截器（Interceptor）模式，这在企业级框架中非常常见。例如 Java Spring 的 HandlerInterceptor、Node.js Express 的中间件（Middleware）、以及 Axios 的请求拦截器，都采用了类似的前置拦截思路。在 AI 编程助手的语境下，这种前置拦截尤为重要——因为 AI 模型可能基于不完整的上下文做出错误判断，PreToolUse 相当于在 AI 决策和实际执行之间增加了一道人工审核或自动校验的安全屏障。

2. PostToolUse — 工具执行后触发

在工具操作完成之后触发。典型应用场景包括：保存代码后自动格式化、修改文件后自动运行相关测试、写入配置后自动重载服务等。

PostToolUse 的自动化逻辑与持续集成/持续部署（CI/CD）流水线的设计理念高度一致。在传统 CI/CD 中，代码提交后会自动触发构建、测试、部署等一系列流水线操作，工具如 Jenkins、GitHub Actions、GitLab CI 都是这一理念的实现。PostToolUse 将这种自动化能力下沉到了开发者的本地编码环节——不必等到代码推送到远程仓库，在本地编辑阶段就能实现即时的质量反馈循环，大幅缩短了问题发现到修复的时间窗口。

3. OnToolError — 执行失败时触发

仅在工具执行出错时才触发。这个 Hook 非常实用，可以配置为自动分析报错原因、收集错误日志，甚至尝试自动修复常见问题。

OnToolError 的设计与现代软件工程中的可观测性（Observability）理念密切相关。可观测性强调通过日志（Logs）、指标（Metrics）、追踪（Traces）三大支柱来理解系统的内部状态。在 AI 辅助编程场景中，工具执行失败的原因可能涉及环境配置、依赖缺失、权限不足等多种因素。OnToolError 提供了一个统一的错误捕获入口，类似于 Sentry、Datadog 等 APM（应用性能监控）工具在生产环境中的角色，但作用于开发阶段，帮助开发者快速定位和解决 AI 操作中的异常问题。

4. Notification — 通知时触发

当 Claude 发送通知时触发，可以用来自定义提示信息的展示方式，或者将通知转发到其他渠道（如 Slack、钉钉等）。

5. OnPrompt — 输入问题时触发

每次你向 Claude 输入问题时触发。可以用来自动补充上下文信息、加载项目配置，或者在对话开始前执行环境检查。

实战演示：配置文件删除保护

下面通过一个具体案例，演示如何利用 Claude Code Hooks 配置一个防止误删文件的安全机制。

第一步：创建 Hook 配置

在 Claude Code 中输入 /hooks，选择第一个选项 PreToolUse（工具执行前触发），然后点击「增加一个新的配置」。

第二步：编写提示词

在提示词输入框中，写入以下逻辑描述：

判断当前即将执行的操作是否包含删除文件（比如 rm、delete、unlink 等命令）。如果是，则提示：「正在删除文件，可能不可恢复，请确认是否继续」，并让用户输入 Yes 或 No 来决定是否执行。

编写完成后点击确定，选择项目级别设置（这样该 Hook 只在当前项目生效），然后退出配置界面。

Claude Code Hooks 支持项目级别和全局级别两种配置作用域，这与许多开发工具的配置分层策略一致。例如 Git 的 .gitconfig 分为系统级、用户级和仓库级，ESLint 的配置文件也支持逐级覆盖。项目级别配置通常存储在项目根目录下，随代码仓库一起版本管理，适合团队共享的规范性 Hook（如代码格式化规则）；全局级别配置则存储在用户主目录下，适合个人偏好类的 Hook（如自定义通知方式）。合理区分两者的使用场景，可以避免配置冲突，同时实现团队规范与个人习惯的平衡。

第三步：验证配置

重新输入 /hooks 可以看到刚才创建的配置已经出现在列表中。

第四步：触发测试

以一个包含登录页面的项目为例，尝试让 Claude 删除登录页面文件。当执行删除命令时，Hook 立即生效，弹出醒目的警告提示：

⚠️ 危险操作：正在删除文件，删除后不可恢复，请确认是否继续删除。

• 输入 Yes：确认删除，操作继续执行
• 输入 No：取消删除，操作被拦截

这个简单的配置，就能有效防止在开发过程中因 AI 误判而导致的文件丢失问题。

Hooks 的更多实用场景

除了文件删除保护，Claude Code Hooks 还有很多值得探索的应用方向：

• 代码自动格式化：在 PostToolUse 中配置，每次文件保存后自动运行 Prettier、ESLint 等格式化工具。Prettier 是一款主张「固执己见」（Opinionated）的代码格式化工具，它通过最小化配置选项来消除团队中关于代码风格的争论，支持 JavaScript、TypeScript、CSS、HTML、Markdown 等多种语言。ESLint 则是 JavaScript/TypeScript 生态中最主流的静态代码分析工具，不仅能检查代码风格，还能发现潜在的逻辑错误和安全漏洞。两者通常配合使用：Prettier 负责格式美化，ESLint 负责质量检查。将它们集成到 PostToolUse Hook 中，意味着每次 AI 修改代码后都会自动执行格式化和质量检查，确保 AI 生成的代码也符合团队的编码标准。

• 自动化测试：修改代码文件后，自动触发相关单元测试，第一时间发现回归问题

• 提交前质量检查：在代码提交（git commit）前自动运行 lint 检查和测试套件，确保代码质量

• 智能错误诊断：利用 OnToolError Hook，在构建失败时自动分析错误日志并给出修复建议

• 上下文自动增强：通过 OnPrompt Hook，在每次对话时自动加载项目的架构文档和编码规范

总结

Claude Code Hooks 是一个被严重低估的功能。它的设计理念很简单——在正确的时机自动做正确的事，但带来的效率提升却是实实在在的。通过合理配置 PreToolUse、PostToolUse、OnToolError、Notification、OnPrompt 这五种触发时机，你可以构建一套完整的自动化工作流，将开发过程中的重复操作降到最低。

对于日常高频使用 Claude Code 的开发者来说，花 10 分钟配置几个常用的 Hooks，长期来看能节省大量时间，同时还能降低误操作的风险。建议从最简单的文件保护和代码格式化开始，逐步扩展到更复杂的自动化场景。