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 直接执行下半段。具体差异行为WindowsCMDmacOS / Linuxbash首行: CMDBLOCK当作文本标签直接跳过:是空操作开启 heredocbatch 段落逐行执行校验参数、按序找 bash.exe、跑目标脚本整段作为 heredoc 内容被忽略收尾exit /b终止不会落到下半段heredoc 结束后执行exec bash ...Windows 侧按C:\Program Files\Git\bin\bash.exe、C:\Program Files (x86)\Git\bin\bash.exe、PATH 里的 bash 三个位置依次找找不到就静默退出 0——插件不报错只是这次钩子被跳过。跨平台钩子三步配好文件结构 hooks.json 关键配置文件布局只需三个文件——hooks/ ├── hooks.json # 配置入口指向包装器 ├── run-hook.cmd # polyglot 包装器跨平台唯一入口 └── session-start # 真实钩子逻辑注意没有 .sh 后缀它做了什么入口永远是包装器具体逻辑放在无扩展名的 bash 脚本里脚本名当作参数传进去。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 的引号解析坑。写逻辑脚本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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考