Claude Code 在 Windows 上的常见坑：Git Bash 还是 PowerShell、路径反斜杠、假报错、WSL 怎么选

本文根据 Claude Code 官方文档《Advanced setup》《Tools reference》《Configure permissions》《Hooks reference》《Extend Claude with skills》《Troubleshooting》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。本站（bigolab.com）不是 Anthropic 官方网站。

适用于谁

• 已经在 Windows 上装好 Claude Code，但碰到命令跑不起来、路径对不上、莫名其妙的「错误」的人；
• 不知道自己的 Claude 到底在用 Git Bash 还是 PowerShell 的人；
• 在原生 Windows 和 WSL 之间犹豫的人。

安装方式怎么选、装不上怎么办，见 /guides/claude-code-install-methods-git-npm-official 和 /guides/claude-code-install-slow-stuck-failed，本文不重复。

结论先说

1. Claude 在 Windows 上有两种 shell 工具：Bash 和 PowerShell。 官方说：没装 Git for Windows 时，命令通过 PowerShell 工具运行；装了就用 Git Bash 作为 Bash 工具，同时 PowerShell 工具也可用（claude.ai 和 Console 账号默认开）。
2. 找不到 Git Bash 就告诉它在哪：在 settings.json 的 env 里设 CLAUDE_CODE_GIT_BASH_PATH，官方示例是 C:\\Program Files\\Git\\bin\\bash.exe。
3. 「报错」不一定是真错。 官方列了几种：grep/rg 没匹配到、git diff 有差异、where.exe 找不到、robocopy 返回 1 到 7，都会显示 Exit code 1 之类，但命令没有失败。
4. 路径别混着写。 权限规则里 Windows 路径会先转成 POSIX 形式；钩子收到的文件路径却是反斜杠，用正斜杠写的判断永远匹配不上。
5. 原生 Windows 不支持沙箱，WSL 2 支持。 这是官方对照表里最关键的差别。

图：本站根据 Claude Code 官方文档：Advanced setup 整理的示意图

坑一：到底用的是哪个 shell

症状：Claude 写的命令是 export、ls -la、&&，在你机器上报错；或者它写 PowerShell 语法时，又在 Bash 里不认。

官方的机制是：

• 没有 Git for Windows：只有 PowerShell 工具，Claude Code 根本不注册 Bash 工具。
• 有 Git for Windows：Bash 工具可用；PowerShell 工具对 claude.ai 和 Console 账号默认开启，通过 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 使用时，要设环境变量 CLAUDE_CODE_USE_POWERSHELL_TOOL=1 才开，设为 0 则关闭。
• PowerShell 工具开启时，官方说 Claude 把 PowerShell 当作主要 shell，Bash 工具在装了 Git Bash 的情况下仍可用于 POSIX 脚本。

怎么确认？直接问它，或者看项目里用的是哪种语法。然后在 CLAUDE.md 里写明约定，免得它每次猜。

提示词 1：让 Claude 报告当前环境并写进 CLAUDE.md

text
请告诉我你当前能用的 shell 工具有哪些（Bash、PowerShell），各自跑在什么环境里。分别运行 uname 或 $PSVersionTable，确认版本。
然后在 CLAUDE.md 里加一节「运行环境」，写明：操作系统是 Windows；项目的命令应优先用【PowerShell / Git Bash】写；路径用【正斜杠 / 反斜杠】；不要使用 Linux 才有的命令（除非在 Git Bash 里）。
先把要加的内容给我看，我同意后再写。

还有一个容易漏的坑，官方在 PowerShell 一节写了：**在装了 Git Bash 的 Windows 上，一旦你给 Bash 加了拒绝规则（哪怕是 Bash(git push ) 这种带范围的），PowerShell 工具会被自动关闭*，因为 Bash 规则管不到 PowerShell，留着它会绕过你的规则。解决办法：设 CLAUDE_CODE_USE_POWERSHELL_TOOL=1，或者给 PowerShell 也加一条对应的拒绝规则，如 PowerShell(git push *)。否则 PowerShell 会被悄悄关掉，没有任何警告。

坑二：路径

权限规则里的路径。 官方说明：Windows 上，路径在匹配前会被标准化成 POSIX 形式，C:\Users\alice 变成 /c/Users/alice。所以想匹配整个 C 盘下任意位置的 .env，规则要写 //c//.env；匹配所有盘符用 ///.env。官方示例里 Read(./.env) 这种相对项目目录的写法照常使用。

钩子收到的路径。 官方说：Windows 上 Write、Edit、Read 的 file_path 永远是绝对路径，而且用反斜杠，即使钩子跑在 Git Bash 里。你的脚本里如果用 /src/ 这种正斜杠判断，永远匹配不上，钩子等于没写，调用照常放行。官方的修法：先把反斜杠换成正斜杠，在 Bash 里是 FILE_PATH="${FILE_PATH//\\//}"，在 Python 里是 file_path.replace("\\", "/")，再匹配 /src/ 这样的路径片段。

网络路径。 官方说，命令参数里带 UNC 路径（\\server\share\file）会弹权限提示，因为访问网络路径可能把你的 Windows 凭据发给目标主机；读文件工具读网络路径也要单独检查，而且这类路径不能直接加成工作目录。官方的办法：把共享映射成盘符，再用 --add-dir 加，例如共享映射为 Z:，在 PowerShell 里运行 claude --add-dir Z:\。

坑三：不是错误的「错误」

官方在 PowerShell 一节列了这些情况，都显示 Error: Exit code 1，但命令没失败，你什么都不用做：

• grep、rg、findstr、git grep 没找到匹配（它们用退出码 1 表示没匹配）；
• git diff 发现有差异（退出码 1 表示有不同）；
• where.exe 没找到、fc.exe、diff.exe 发现文件不同；
• robocopy 返回 1 到 7（官方说 0 到 7 都是在汇报结果，8 以上才是失败）。

官方还说，当这类搜索在更长的命令里（例如 rg foo | Out-Null）时更容易冒出这个提示。把这个知识交给 Claude，它就不会在「没匹配」时瞎找原因。

提示词 2：解释一段看起来像报错的输出

text
下面这段命令输出里出现了 Error: Exit code 1。请判断它是真的失败，还是只是「没有匹配」或「文件不同」这类正常的退出码：
【粘贴命令和输出】
说明你判断的依据；如果是真错，给出下一步排查命令，先不要修改任何文件。

坑四：脚本、技能和钩子里的 shell

• 钩子：每个命令类钩子可以加 "shell": "powershell"，直接用 PowerShell 运行，不依赖 PowerShell 工具开关；没装 Git Bash 时，钩子默认用 PowerShell，Bash 写的脚本可能失败。官方的修法是装 Git for Windows，或设 CLAUDE_CODE_GIT_BASH_PATH，然后开新会话。
• 钩子匹配：要拦截 shell 命令，matcher 写 Bash|PowerShell，只写 Bash 不够。
• 钩子引用脚本：PowerShell 里引用项目目录写 ${CLAUDE_PROJECT_DIR} 或 $env:CLAUDE_PROJECT_DIR，不要写 $CLAUDE_PROJECT_DIR，那会被解析成空变量。
• npm、npx 这类 .cmd 文件：官方说，exec 形式的钩子需要指向真正的可执行文件（.exe），npm、npx、eslint 等在 node_modules/.bin 里装的 .cmd、.bat 垫片不是可执行文件，没有 shell 就启动不了。
• 技能里的预执行命令：frontmatter 里写 shell: powershell 可以让它们在 PowerShell 里运行，要求 PowerShell 工具已开启；写死 shell: bash 而电脑没有 Git Bash，调用会直接失败。

钩子的完整例子见 /guides/claude-code-hooks-run-tests-before-commit，基础见 /guides/claude-code-hooks。

坑五：执行策略、编码和环境变量

• 执行策略。官方说，PowerShell 工具会用 -ExecutionPolicy Bypass 启动，仅作用于该进程，所以 .ps1 脚本在默认 Windows 上也能运行，但不会覆盖组策略；想遵守机器的有效策略，设 CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1。
• 编码。官方说，PowerShell 5.1 里用 > 和 >> 重定向写出的是 UTF-8 文件，Claude Code 往原生命令标准输入传的文本也是 UTF-8。
• 环境变量不跨命令保留。官方说，Bash 工具里一条命令的 export 在下一条命令里没有；想持久化，设 CLAUDE_ENV_FILE 指向一个脚本，或用 SessionStart 钩子。工作目录则会保留，只要还在项目目录或你用 --add-dir 加的目录内。
• 不加载配置文件。官方的已知限制：PowerShell 工具不会加载 PowerShell 的 profile，你在 profile 里设的别名和变量它看不到。

坑六：原生还是 WSL

官方把三种方式摆在一张表里：

• 原生 Windows：不需要任何前置；Git for Windows 可选；不支持沙箱；适合 Windows 原生的项目和工具。
• WSL 2：需要先启用 WSL 2；支持沙箱；适合 Linux 工具链，或需要沙箱化执行命令的场景。
• WSL 1：需要启用 WSL 1；不支持沙箱；WSL 2 用不了时才考虑。

WSL 里有两点要注意：一是官方排错说，跨文件系统访问有读盘性能损失，可能导致搜索匹配比预期少，建议项目放在 Linux 文件系统（/home/），而不是 /mnt/c/；二是官方 Chrome 集成文档写明，不支持 WSL。沙箱的说明见 /guides/claude-code-sandbox-security。

图：本站根据官方文档整理的示意图

一次排查流程

提示词 3：新项目的 Windows 自检

text
请检查这个项目在我的 Windows 环境里能不能正常工作：
1）列出 package.json 或脚本里用到的所有命令，标出哪些在 PowerShell 里不能直接用（比如 rm -rf、export、&&）；
2）检查是否有硬编码的 Linux 路径（如 /tmp、/usr/）；
3）检查换行符设置，仓库里有没有 .gitattributes，脚本文件是否会被转成 CRLF 而在 Git Bash 里出错；
4）给出修改建议，用跨平台的写法（Node 脚本或 npm 包）替代，先不要改文件。

第 3 条是通用的 Windows 开发常识，官方文档没有专门写。

常见问题

Q：不装 Git for Windows 行不行？

行，官方说它是可选的，没装时 Claude 用 PowerShell。装了可以用 Bash 工具，对只会 Bash 写法的脚本更方便。

Q：以管理员身份运行 Claude Code？

官方说明安装不需要管理员权限。是否以管理员运行，官方文档没有推荐，建议不要。

订阅和额度

环境问题多半靠读取少量配置就能解决，用不了多少额度。订阅选择见 /chongzhi/claude-code，价格和额度以官方页面当前显示为准。

相关教程

• /guides/claude-code-getting-started：Claude Code 入门
• /guides/claude-code-terminal-garbled-which-terminal：终端乱码与终端选择
• /guides/claude-code-task-done-notification-sound-windows：Windows 任务完成提醒

参考资料

• Claude Code 文档：Advanced setup — https://code.claude.com/docs/en/setup
• Claude Code 文档：Tools reference — https://code.claude.com/docs/en/tools-reference
• Claude Code 文档：Configure permissions — https://code.claude.com/docs/en/permissions
• Claude Code 文档：Hooks reference — https://code.claude.com/docs/en/hooks
• Claude Code 文档：Extend Claude with skills — https://code.claude.com/docs/en/skills
• Claude Code 文档：Troubleshooting — https://code.claude.com/docs/en/troubleshooting