Hooks 常见坑点

原文链接：https://anthropic.skilljar.com/claude-code-in-action/303247

标签： 讲义

---

在使用 Hooks 的过程中，你可能会遇到一些常见问题。本节总结了这些坑点及其解决方案，帮助你更顺利地使用 Hooks。

1. Hook 不触发

问题： 配置了 Hook 但完全没有触发

常见原因：

• JSON 语法错误
• 文件路径或命令拼写错误
• runOnlyWhen 条件过于严格
• Claude Code 未重新加载配置

解决方案：

• 检查 JSON 格式是否有效
• 验证命令在终端可以直接运行
• 简化条件表达式测试
• 重启 Claude Code 重新加载配置

2. 条件表达式不生效

问题： runOnlyWhen 条件没有按预期工作

正确写法示例：

"runOnlyWhen": "changedFiles匹配 **/*.ts"

常见错误：

• 使用了单引号而非双引号
• 条件语法拼写错误
• 文件模式没有正确使用 glob 语法

3. Hook 超时

问题： Hook 执行时间过长导致超时

解决方案：

• 增加 timeout 值
• 优化命令减少执行时间
• 使用 continueOnError: true 避免阻塞

{
  "command": "npm run long-task",
  "timeout": 300000,
  "continueOnError": true
}

4. 循环触发

问题： Hook 触发自身导致无限循环

场景： Hook 修改了文件，又触发同一个 Hook

解决方案：

• 在 runOnlyWhen 中排除 Hook 相关的文件
• 使用更精确的文件匹配条件
• 使用 ignorePatterns 排除特定文件

5. 环境差异

问题： 本地运行正常但在 CI 环境中失败

解决方案：

• 确保 CI 环境安装了所有依赖
• 使用绝对路径或环境变量
• 在不同环境中测试 Hook

6. 权限问题

问题： Hook 命令没有执行权限

解决方案：

• 确保脚本文件有执行权限：chmod +x script.sh
• 使用完整命令路径：/usr/bin/npm run test

7. 输出干扰

问题： Hook 的输出干扰 Claude 的响应

解决方案：

• 将输出重定向到文件：command > /dev/null 2>&1
• 使用静默模式运行命令
• 只在需要时输出关键信息

---

下一节： 17 实用的 Hooks