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