菜鸟教程
教程 claude-code-in-action tutorial

Hooks 常见坑点

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

标签： 讲义

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

1. Hook 不触发

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

常见原因：

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

解决方案：

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

2. 条件表达式不生效

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

正确写法示例：

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

常见错误：

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

3. Hook 超时

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

解决方案：

  • 增加 timeout 值
  • 优化命令减少执行时间
  • 使用 continueOnError: true 避免阻塞
json 
{
  "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

相关内容