【Bug已解决】Claude Code Hooks 报错 jq: command not found 解决方案

【Bug已解决】Claude Code Hooks 报错 jq: command not found 解决方案

1. 问题描述

在 Windows 上给 Claude Code 配置 Hooks（生命周期钩子脚本）功能后，触发对应事件时终端报错：

Hook execution failed: 'jq' is not recognized as an internal or external command, operable program or batch file.

1.1 具体现象

1. Hooks 脚本里用了jq命令处理 JSON 格式的 Hook 输入/输出数据
2. 在 macOS/Linux 上完全正常，换到 Windows 上就报错
3. 检查 Hooks 配置本身的 JSON 语法没有问题
4. 团队里跨平台协作时，只有 Windows 用户遇到这个报错

这个问题的本质很直接——jq是一个类 Unix 系统常见的命令行 JSON 处理工具，macOS/Linux 通常预装或很容易安装，而 Windows 默认并不自带这个工具，很多 Hooks 教程里的示例脚本习惯性地使用jq来解析 Hook 传入的 JSON 数据，直接照搬到 Windows 环境就会报错。

2. 原因分析

Claude Code 的 Hooks 机制会在特定事件（如 PreToolUse、PostToolUse）触发时，把结构化的上下文信息以 JSON 格式传递给你配置的 Shell 命令。很多社区教程为了方便地从这段 JSON 里提取字段，会在 Hook 脚本里调用jq：

{ "hooks": { "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "jq -r '.tool_input.command'" }] }] } }

jq本身不是 Claude Code 内置提供的，而是依赖运行环境本身已经安装好这个工具。Windows 系统默认的 PowerShell/CMD 环境里没有预装jq，自然会报"命令未找到"。

3. 解决方案

方案一：Windows 上手动安装 jq（最直接）

# 使用 winget 安装（Windows 10/11 自带的包管理器） winget install jqlang.jq # 或使用 Chocolatey choco install jq # 安装完成后验证 jq --version

方案二：改用 PowerShell 原生的 JSON 处理能力，不依赖 jq

Windows 上更"原生"的做法是用 PowerShell 自带的ConvertFrom-Json替代jq：

{ "hooks": { "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "powershell -Command \"$input | ConvertFrom-Json | Select-Object -ExpandProperty tool_input | Select-Object -ExpandProperty command\"" }] }] } }

方案三：编写跨平台兼容的 Hook 脚本，而非直接在配置里写单行命令

对于复杂的 Hook 逻辑，建议写成独立的脚本文件（用 Node.js/Python 这类跨平台脚本语言实现），而不是依赖某个特定平台才有的命令行工具：

#!/usr/bin/env python3 import sys, json data = json.load(sys.stdin) command = data.get("tool_input", {}).get("command", "") print(command)

Python/Node.js 在 Windows/macOS/Linux 上的行为高度一致，能从根源上避免这类平台特有命令缺失的问题。

方案四：在 WSL 环境下运行 Claude Code，复用类 Unix 工具链

如果本身已经习惯在 WSL（Windows Subsystem for Linux）里进行开发，直接在 WSL 环境内使用 Claude Code 并配置 Hooks，能天然获得完整的类 Unix 命令行工具支持，不需要在 Windows 原生环境里逐一补装。

方案五：团队协作场景，在项目文档中明确标注所需的外部依赖

如果团队的 Hooks 配置依赖jq等外部工具，建议在项目 README 或环境搭建文档里明确列出这类依赖，并给出各平台的安装指引，而不是让每个新成员各自踩坑发现。

4. 各方案对比总结

5. 常见问题 FAQ

5.1 除了 jq，Hooks 脚本还可能依赖哪些类 Unix 工具？

常见的还包括grep、sed、awk等经典文本处理工具，这些在 Windows 原生环境下同样默认缺失，排查思路和jq完全一致——安装对应工具，或改用跨平台脚本语言重写。

5.2 用 Git Bash 执行这些命令会不会好一些？

会有一定改善，Git Bash 自带了部分类 Unix 工具（如grep、sed），但不一定包含jq，仍然可能需要单独安装，效果因具体环境而异。

5.3 团队里 macOS 和 Windows 用户各占一半，应该统一用哪种方式？

建议优先选择"跨平台脚本语言编写 Hook 逻辑"这个方案，能一次编写、多平台复用，避免维护两套针对不同操作系统的 Hook 配置。

5.4 排查清单速查表

□ 1. 确认报错的具体命令名称（jq/grep/sed 等） □ 2. 判断该命令是否为 Windows 默认不自带的类 Unix 工具 □ 3. 选择手动安装该工具，或改用 PowerShell/跨平台脚本重写 □ 4. 团队协作场景在文档中标注清楚所需的外部依赖 □ 5. 评估是否适合统一迁移到 WSL 环境下开发

6. 总结

Hooks 报jq: command not found的本质是Hook 脚本依赖了 Windows 默认不自带的类 Unix 命令行工具，而不是 Claude Code Hooks 机制本身有问题。核心处理思路：

1. 最简单的方式是直接在 Windows 上手动安装jq；
2. 更彻底的方式是把 Hook 脚本改写为跨平台脚本语言（Python/Node.js）实现，从根源上避免平台差异；
3. 团队协作场景务必在文档中明确标注 Hooks 依赖的外部工具，减少新成员重复踩坑。

最佳实践建议：设计 Hooks 逻辑时，优先考虑团队内所有操作系统平台的兼容性，而不是只以自己习惯的开发环境为标准编写脚本。