企业官网建设流程全解析

Claude Code 钩子在 Windows 上跑不动？Superpowers 跨平台钩子配置完整指南

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers

在 Superpowers 跨平台开发里，最容易卡住的是 Claude Code 插件钩子：同一份脚本，得在 Windows、macOS、Linux 三台上都跑起来。Superpowers 用一层 polyglot 包装脚本加一个统一入口把这件事做掉了，本文把原理拆开讲，并整理 4 个高频报错的排查办法。

Windows 上钩子跑不动？先看这 3 个典型失败现场

🪟 跨平台钩子调试的挫败感很具体：Windows 上双击 .sh，文件被文本编辑器打开而不是执行；把命令手动丢进 CMD，回一句'bash' is not recognized as an internal or external command；脚本里写的$CLAUDE_PLUGIN_ROOT在 CMD 里原样输出，路径里反斜杠正斜杠混着走。三个平台三套报错，逐个环境排查，半天就没了。

🧩 Superpowers 的解法很简单：真正的钩子逻辑只写一份 bash 脚本，外面包一层 polyglot（同一文件可被 CMD 和 bash 分别解析）的包装器，hooks.json 只配置这一个入口。

polyglot 包装器原理：同一份脚本被 CMD 和 bash 怎么解析

入口文件是hooks/run-hook.cmd，结构长这样：

: << 'CMDBLOCK' @echo off set "HOOK_DIR=%~dp0" ... 三个位置查找 bash.exe 并执行目标脚本 ... exit /b CMDBLOCK # Unix: run the named script directly SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" SCRIPT_NAME="$1" shift exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

它做了什么：Windows 上由 CMD 执行上半段 batch 找到 bash 再拉起脚本；Unix 上整段 batch 被 heredoc 吃掉，bash 直接执行下半段。具体差异：

Windows 侧按C:\Program Files\Git\bin\bash.exe、C:\Program Files (x86)\Git\bin\bash.exe、PATH 里的 bash 三个位置依次找；找不到就静默退出 0——插件不报错，只是这次钩子被跳过。

跨平台钩子三步配好：文件结构 + hooks.json 关键配置

1. 文件布局：只需三个文件——

hooks/ ├── hooks.json # 配置入口，指向包装器 ├── run-hook.cmd # polyglot 包装器（跨平台唯一入口） └── session-start # 真实钩子逻辑，注意没有 .sh 后缀

它做了什么：入口永远是包装器，具体逻辑放在无扩展名的 bash 脚本里，脚本名当作参数传进去。

2. hooks.json 注册事件：

{ "hooks": { "SessionStart": [ { "matcher": "startup|clear|compact", "hooks": [ { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start", "shell": "bash" } ] } ] } }

它做了什么：所有事件统一走run-hook.cmd session-start这一个命令，session-start只是参数；💡"shell": "bash"强制走 Git Bash，绕开 CMD/PowerShell 的引号解析坑。

3. 写逻辑脚本：session-start是普通 bash 脚本，优先只用内置命令（printf、${s//old/new}这类参数展开），变量扩展一律加引号"$VAR"，不依赖 sed 等外部命令。

⚠️ 容易漏的一点：钩子脚本不要带 .sh 后缀。Claude Code 在 Windows 上会给路径含 .sh 的命令自动前置 bash，绕过你的包装器，名字对不上就直接失效。

这 4 个跨平台钩子报错最常见：逐个对症处理 🔧

'bash' is not recognized as an internal or external command

原因：包装器三个位置都没找到 bash，多半是 Git 装在非默认路径。解法：把 Git for Windows 装到默认位置，或把 bash 加进 PATH；注意找不到时包装器是静默退出，症状看起来像"钩子没反应"。

cygpath: command not found

原因：老式写法用bash -c "..."调脚本，bash 没以登录 shell 启动时 PATH 里没有 cygpath。解法：加-l以登录 shell 启动；或改用"脚本路径当参数传"的写法，bash 自己会处理C:\路径，不再需要 cygpath。

路径里混出 \/ 直接报错

原因：${CLAUDE_PLUGIN_ROOT}展开为以反斜杠结尾的 Windows 路径，再拼/hooks/...就串成一串。解法：整段路径加引号交给 bash 自动转换，或用cygpath -u对完整路径做一次转换，别分段手拼。

钩子在 macOS 正常、在 Windows 无响应

原因：脚本名带了 .sh 后缀，触发 Windows 自动检测后去执行一个不存在的文件名。解法：改成无扩展名命名，把名字作为参数传给包装器。

✅ 跨平台钩子的关键不是给每个系统各写一套，而是让两个解释器各取一段、只留一个入口——Superpowers 的入口就是 run-hook.cmd。完整原理见 docs/windows/polyglot-hooks.md，参考实现看 hooks/run-hook.cmd 与 hooks/session-start。

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers