# 定义 Hooks

URL: https://caijiao.org/claude-code-in-action/14-defining-hooks
Source: docs/claude-code-in-action/14-defining-hooks.md
Description: 学习如何在 .claude/settings.json 中定义 Hooks，掌握各种 Hook 类型和配置选项

原文链接：[https://anthropic.skilljar.com/claude-code-in-action/303245](https://anthropic.skilljar.com/claude-code-in-action/303245)

**标签：** 视频 + 讲义

---

了解 Hooks 的概念后，本节介绍如何定义你自己的 Hooks。Claude Code 的 Hooks 存储在项目根目录的 `.claude` 目录中，使用 JSON 格式配置。

## Hooks 文件结构

Hooks 定义存放在 `.claude/settings.json` 文件中。一个基本的 Hook 定义如下：

```json
{
  "hooks": {
    "BeforeModify": [
      {
        "name": "Run linter",
        "command": "npm run lint"
      }
    ]
  }
}
```

这个示例定义了一个在修改文件前运行的 Hook，会自动运行 `npm run lint`。

## 可用的 Hook 类型

Claude Code 支持多种 Hook 类型：

- **BeforeModify**：Claude 即将修改文件之前
- **AfterModify**：Claude 修改文件之后
- **BeforeAgentLoop**：每次 Claude 思考之前
- **AfterAgentLoop**：每次 Claude 思考之后
- **OnDiskFreeSpaceLow**：磁盘空间不足时
- **OnError**：发生错误时

## 配置选项

每个 Hook 可以配置以下属性：

| 属性 | 说明 |
|------|------|
| `name` | Hook 的描述名称 |
| `command` | 要执行的命令 |
| `description` | 更详细的说明 |
| `runOnlyWhen` | 条件表达式，只有满足时才执行 |
| `timeout` | 超时时间（毫秒） |
| `continueOnError` | 失败时是否继续执行主流程 |

## 完整示例

```json
{
  "hooks": {
    "AfterModify": [
      {
        "name": "Run tests",
        "command": "npm test",
        "description": "每次修改代码后运行测试",
        "timeout": 120000,
        "continueOnError": false
      }
    ],
    "BeforeModify": [
      {
        "name": "Check types",
        "command": "npm run typecheck",
        "description": "修改前检查 TypeScript 类型",
        "runOnlyWhen": "file匹配 src/**/*.ts"
      }
    ]
  }
}
```

---

**下一节：** [15 实现一个 Hook](./15-implementing-a-hook)