【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 具体现象Hooks 脚本里用了jq命令处理 JSON 格式的 Hook 输入/输出数据在 macOS/Linux 上完全正常换到 Windows 上就报错检查 Hooks 配置本身的 JSON 语法没有问题团队里跨平台协作时只有 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 处理能力不依赖 jqWindows 上更原生的做法是用 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 工具链如果本身已经习惯在 WSLWindows Subsystem for Linux里进行开发直接在 WSL 环境内使用 Claude Code 并配置 Hooks能天然获得完整的类 Unix 命令行工具支持不需要在 Windows 原生环境里逐一补装。方案五团队协作场景在项目文档中明确标注所需的外部依赖如果团队的 Hooks 配置依赖jq等外部工具建议在项目 README 或环境搭建文档里明确列出这类依赖并给出各平台的安装指引而不是让每个新成员各自踩坑发现。4. 各方案对比总结方案适用场景推荐指数手动安装 jq最简单直接保持脚本不变⭐⭐⭐⭐⭐改用 PowerShell 原生能力不想额外安装第三方工具⭐⭐⭐⭐编写跨平台脚本长期维护、多人协作的项目⭐⭐⭐⭐⭐WSL 环境运行已习惯 WSL 开发的用户⭐⭐⭐⭐文档标注依赖团队协作规范化⭐⭐⭐⭐5. 常见问题 FAQ5.1 除了 jqHooks 脚本还可能依赖哪些类 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 机制本身有问题。核心处理思路最简单的方式是直接在 Windows 上手动安装jq更彻底的方式是把 Hook 脚本改写为跨平台脚本语言Python/Node.js实现从根源上避免平台差异团队协作场景务必在文档中明确标注 Hooks 依赖的外部工具减少新成员重复踩坑。最佳实践建议设计 Hooks 逻辑时优先考虑团队内所有操作系统平台的兼容性而不是只以自己习惯的开发环境为标准编写脚本。
