# Hooks 常见坑点

URL: https://caijiao.org/claude-code-in-action/16-gotchas-around-hooks
Source: docs/claude-code-in-action/16-gotchas-around-hooks.md
Description: 汇总使用 Hooks 时的常见问题和解决方案，帮助你避免配置错误和性能问题

原文链接：[https://anthropic.skilljar.com/claude-code-in-action/303247](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](./17-useful-hooks)