Claude Code 在 Windows 上的安裝指南：原生或 WSL，並解決常見困擾

Claude Code 最初的目標是 macOS 和 Linux 使用者，Windows 使用者則被引導至 WSL。現在，它推出了原生的 Windows 版本，可以直接從 PowerShell 執行。選擇哪種方式取決於一個關鍵問題：你是否需要沙盒化功能？這篇文章將比較這兩種方法，提供各自的安裝步驟，並彙整了使用者常遇到的問題。

原生 Windows 版本直接在 Windows 上執行，不需要額外條件，但 Git for Windows 是可選的。它不支援沙盒化功能，並使用 Git Bash 或 PowerShell 工具。專案通常存放在 Windows 磁碟機上，且 Linux 工具需要 Windows 版本才能運作，適合 Windows 原生開發環境，例如 .NET 或 Node。

相對地，WSL 2 則是在 WSL 內部執行 Linux 環境（例如 Ubuntu），需要啟用 WSL 2。它支援沙盒化功能，並使用 bash 或 zsh 等 Shell 工具。建議將專案放在 WSL 內部，例如 /home/...，且 Linux 工具可以直接使用其 Linux 版本，適合 Linux 工具鏈或需要沙盒化指令執行的情境。

WSL 1 是第三種選擇，適用於 WSL 2 無法使用的情況；它與原生 Windows 版一樣，不支援沙盒化。值得注意的是，從 WSL 存取 Windows 檔案會大幅降低 I/O 速度。因此，如果選擇 WSL，建議將專案保留在 WSL 內部，例如 ~/projects/ 目錄下。

安裝原生版本的第一步是選擇性安裝 Git for Windows。文件指出這是可選的，但如果你的掛鉤和腳本預設使用 bash，則建議安裝它。Git for Windows 的預設設定即可。安裝後，PowerShell 工具將與 Bash 並存，預設在 claude.ai 和 Console 帳戶中啟用，也可透過設定 CLAUDE_CODE_USE_POWERSHELL_TOOL=1 在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 會話中啟用，設為 0 則關閉此工具。

接著，開啟 PowerShell 並執行 irm https://claude.ai/install.ps1 | iex 來安裝 Claude Code。如果你使用 CMD，指令會有所不同，CMD 提示符號沒有 PS C:\：curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd。

WinGet 也是一個選項，但透過 WinGet 安裝的版本不會自動更新，因此需要定期執行 winget upgrade Anthropic.ClaudeCode。另外，npm 套件也是一種選擇，但需要 Node.js 22 或更高版本。安裝時不需要以管理員身份執行。

安裝完成後，進入你的專案目錄（例如 cd C:\path\to\project），然後執行 claude 啟動。首次執行會提示你登入。你可以執行 claude doctor 來檢查安裝狀況和設定檔的驗證錯誤，而無需啟動會話。如果 Claude Code 無法找到 Git Bash，你可以在設定檔中指定其路徑，例如：{ "env" : { "CLAUDE_CODE_GIT_BASH_PATH" : "C:\\Program Files\\Git\\bin\\bash.exe" } }。

在 WSL 中安裝時，沙盒化指令執行需要 WSL 2；WSL 1 不支援此功能。首先，在具備管理員權限的 PowerShell 中執行 wsl --install 並重新啟動電腦，預設會安裝 Ubuntu。

接著，開啟 Ubuntu 終端機，如果你打算使用 npm 套件，請安裝 Node.js（建議使用 nvm 簡化安裝）。然後，在 WSL 終端機內執行 Linux 指令來安裝 Claude Code，而不是從 PowerShell 或 CMD：curl -fsSL https://claude.ai/install.sh | bash。

對於 VS Code 使用者，請安裝 WSL 擴充功能，然後在 WSL 內部開啟一個資料夾，並將 Claude Code 擴充功能安裝到 WSL 環境中。

使用者常遇到的問題之一是，掛鉤和腳本是透過 Git Bash 執行的。當安裝了 Git for Windows 時，Bash 工具會使用 Git Bash，因此 PowerShell 的 Cmdlet 無法直接使用。此時，你需要明確地呼叫 PowerShell，例如：{ "hooks" : { "PostToolUse" : [ { "matcher" : "Edit|Write" , "hooks" : [ { "type" : "command" , "command" : "powershell -NoProfile -File .claude/hooks/format.ps1" } ] } ] } }。

關於掛鉤的基礎知識，可以參考「使用 Claude Code 掛鉤在儲存時執行 Lint 和格式化」。

在撰寫路徑時，無論是在權限模式還是在 CLAUDE.md 中，正斜線（例如 src/**）在 Windows 上也能正常運作。應避免使用反斜線，因為它們在 JSON 內部需要進行跳脫處理。

如果指令輸出出現亂碼，請將 PowerShell 的輸出編碼設定為 UTF-8，例如：[Console]::OutputEncoding = [System.Text.Encoding]::UTF8。

最後，換行符號也是一個常見問題。由 Windows 編輯器以 CRLF 格式儲存的 CLAUDE.md 或掛鉤腳本，在 Git Bash 下可能會因為多餘的 \r 字符而失敗。建議在 .gitattributes 中設定 *.sh text eol=lf，並將腳本以 LF 格式儲存。