Claude Code Hooks 报错异常处理：解决 Windows 环境下的 jq 命令缺失问题

Claude Code Hooks 报错异常处理：解决 Windows 环境下的 jq 命令缺失问题

一、背景

Claude Code 是一款功能强大的 CLI 工具，它允许开发者通过 Hooks（钩子）机制在特定事件发生时自动执行脚本，从而定制化开发流程。然而，在 Windows 环境中，由于 Shell 环境的多样性（CMD、PowerShell、Git Bash、WSL 等），Claude Code 在调用 Hooks 时可能会遇到环境不一致的问题，导致脚本执行失败。

本文记录了一次典型的故障排查与解决过程：当 Claude Code 执行 stop hooks 时，因 jq 命令缺失而报错。我们将深入分析问题根源，并提供一套完整、可靠的解决方案。

二、问题

2.1报错现象

在使用 Claude Code 时，控制台输出以下错误信息：

● Ran 2 stop hooks
  ⎿  bash ${CLAUDE_PLUGIN_ROOT}/hooks/emit-event.sh
  ⎿  ${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd claude-judge-continuation
  ⎿  Stop hook error: Failed with non-blocking status code: /c/Users/lenovo/.claude/plugins/cache/superpowers-marketplace/claude-session-driver/1.0.1/hooks/emit-event.sh: line 12: jq: command not found

核心错误是：jq: command not found。

2.2问题分析

1. 环境混杂：Claude Code 在 Windows 上运行时，可能会在不同的 Shell 环境之间切换。某些 Hooks 脚本设计为在 Unix-like 环境（如 Git Bash）中运行，但 Claude Code 可能错误地使用了其他环境。

2. 依赖缺失 ：jq 是一个轻量级的命令行 JSON 处理器，许多 Hooks 脚本（特别是处理事件数据的脚本）依赖它来解析和生成 JSON 数据。在 Windows 上，jq 并非系统自带命令，需要单独安装。

3. 路径问题 ：即使系统安装了 jq，如果它不在当前 Shell 环境的 PATH 中，脚本仍无法找到该命令。

根本矛盾在于：Claude Code 没有在一个统一、纯净的 Shell 环境中运行，导致环境变量、命令路径等配置不一致。

三、方案

3.1解决思路

我们的目标是为 Claude Code 建立一个稳定、统一的运行环境，避免跨平台脚本冲突。最佳实践是：

1. 强制指定 Shell 环境 ：通过设置环境变量 CLAUDE_CODE_GIT_BASH_PATH，明确告诉 Claude Code 使用 Git Bash 作为执行 Hooks 的默认 Shell。
2. 在目标环境中安装依赖 ：将 jq 安装到 Git Bash 的 PATH 目录中，确保脚本能在该环境中找到命令。

3.2方案优势

• 一劳永逸 ：解决当前 jq 缺失问题的同时，预防未来可能出现的类似环境冲突。
• 可控性强：明确指定 Shell 环境，避免 Claude Code 自动选择不合适的环境。
• 符合最佳实践：在 Windows 上使用 Git Bash 作为开发 Shell 是常见且推荐的做法。

四、实现

4.1确认 Git for Windows 已安装

1. 确保已安装 Git for Windows。如果尚未安装，请下载并安装。
2. 找到 bash.exe 的路径。默认安装位置为：C:\Program Files\Git\bin\bash.exe。

4.2设置关键环境变量

这是最关键的一步，告诉 Claude Code 使用哪个 Bash 环境。

1. 在 Windows 搜索框中输入 "编辑系统环境变量" 并打开。
2. 点击 "环境变量(N)..." 按钮。
3. 在 "系统变量" 区域，点击 "新建..."。
4. 创建新系统变量：
   • 变量名 : CLAUDE_CODE_GIT_BASH_PATH
   • 变量值 : C:\Program Files\Git\bin\bash.exe（请确保路径与实际安装位置一致）
5. 点击 "确定" 保存所有更改。

4.3安装 jq 到 Git Bash 环境

既然我们已经决定在 Git Bash 环境中运行，就需要将 jq 安装到 Git Bash 能找到的位置。最简单的方法是将 jq 可执行文件放到 Git Bash 的 usr/bin 目录下。

1. 访问 jq 的官方 Windows 发布页：https://github.com/stedolan/jq/releases
2. 下载最新的 64 位 Windows 可执行文件（文件名类似 jq-win64.exe）。
   
3. 将下载的 jq-win64.exe 复制到 Git for Windows 的 usr/bin 目录下：
   • 默认路径：C:\Program Files\Git\usr\bin\
   • 如果找不到，可以在文件资源管理器中搜索 bash.exe，然后进入其所在目录的 ..\usr\bin\
     
4. 重命名 ：将 jq-win64.exe 重命名为 jq.exe。
   
   完成此步骤后，jq 命令就在 Git Bash 的 PATH 中了。

4.4替代安装方法：使用 winget

如果你更喜欢使用包管理器，也可以使用 Windows 包管理器 winget 安装 jq：

winget install jq

这种方法会将 jq 安装到系统 PATH 中，但可能仍需要确保 Git Bash 能识别该路径。

五、结果

5.1验证环境配置

重要：关闭并重新打开所有终端窗口（包括 VS Code 内置终端），使新的环境变量生效。

1. 验证环境变量：

   • 在 Git Bash 中：echo $CLAUDE_CODE_GIT_BASH_PATH
   • 在 PowerShell 中：$env:CLAUDE_CODE_GIT_BASH_PATH

   应输出设置的 bash.exe 完整路径。

2. 验证 jq 命令：

   • 在终端中执行：jq --version
   • 应正确输出版本号，而不是报错。
     

5.2验证失败与二次尝试

如果 jq --version 仍然报错，可以尝试使用 winget 安装：

winget install jq

安装后再次验证：

5.3重新运行 Claude Code

在新的终端中重新启动 Claude Code，之前的错误应该已彻底解决：

六、总结与延伸阅读

6.1经验总结

本次故障排查揭示了在 Windows 上使用跨平台开发工具时的一个常见陷阱：环境不一致 。Claude Code Hooks 报错表面上是 jq 命令缺失，实质上是运行环境配置矛盾。

通过以下两个关键措施，我们不仅解决了当前问题，还建立了更健壮的开发环境：

1. 环境统一 ：设置 CLAUDE_CODE_GIT_BASH_PATH 环境变量，强制 Claude Code 在指定的 Shell 环境中运行。
2. 依赖管理 ：将必要工具（如 jq）安装到目标环境的 PATH 中。

6.2最佳实践建议

1. 环境隔离：为不同的开发工具建立明确的环境边界，避免相互干扰。
2. 依赖显式声明：项目文档中应明确列出所有命令行依赖及其安装方法。
3. 版本管理 ：对于像 jq 这样的工具，考虑使用版本管理器或容器化技术确保环境一致性。

通过这次故障解决，我们不仅修复了一个具体的技术问题，更重要的是建立了一套应对类似环境配置问题的系统方法。在跨平台开发日益普遍的今天，掌握环境配置和故障排查技能是每个开发者的必备能力。