如果你在 Windows 筆電上第一次裝 Claude Code，常見卡點通常是環境選錯。專案明明在 WSL 裡，卻從 PowerShell 開 Claude Code；公司不准開 WSL2，卻照舊文硬裝 Ubuntu；或是 repo 放在 OneDrive、/mnt/c/、中文路徑裡，安裝成功後讀檔和搜尋仍然慢到不能用。
先把問題縮小成一個決定：這台 Windows 要用原生 Claude Code，還是把 Claude Code 裝進 WSL2？原生 Windows 適合 Windows 工具鏈與公司管控環境；WSL2 適合 Linux 指令、容器、sandbox 和長期開發流程。選好路線後，再照官方指令安裝、跑驗證、用一個低風險 repo 任務測通，會比反覆重裝有效很多。
先用三個問題選路線
| 你的情境 | 建議路線 | 原因 |
|---|---|---|
| 專案主要是 .NET、PowerShell、Windows 本機工具，檔案也放在 Windows 路徑 | 原生 Windows 或 WinGet | 不需要多一層 Linux 環境，和現有工具鏈比較近。 |
| 團隊平常用 macOS/Linux、Docker、Bash script、ripgrep、MCP server 或需要 sandbox | WSL2 | Anthropic 文件把 WSL2 列為支援 sandbox 與 Linux toolchain 的路線。 |
| 公司 IT 不允許 WSL2、不能開虛擬化，或只想短時間試用 | 原生 Windows | 官方支援 PowerShell/CMD；裝 Git for Windows 可讓 Bash tool 比較完整。 |
repo 很大、搜尋很多檔案，而且現在放在 /mnt/c/ 或 OneDrive | 優先整理專案位置，再決定 | WSL 跨檔案系統讀寫會慢；先把正式 repo 放到 WSL 的 /home 或避開同步資料夾。 |
這篇只處理 Windows 安裝與驗收。費用、日常任務、安全設定、hooks、MCP 與團隊推行，請回到 Claude Code 完全指南 或 Claude Code 新手入門。
路線 A：原生 Windows 安裝
Anthropic 目前把原生安裝列為推薦路線，Windows 可用 PowerShell、CMD 或 WinGet。官方 setup 文件也寫明，Windows 原生安裝不需要以系統管理員身分執行；Git for Windows 是可選項，但裝了以後 Claude Code 可以用 Git Bash 作為 Bash tool，沒裝則會用 PowerShell tool。
PowerShell 用這行：
irm https://claude.ai/install.ps1 | iexCMD 用這行：
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd如果偏好 Windows 套件管理，也可以用 WinGet：
winget install Anthropic.ClaudeCodePowerShell 和 CMD 最常見的錯誤，是把另一個 shell 的指令貼進來。看到 && 不是有效語法，通常是把 CMD 指令貼到 PowerShell；看到 irm 找不到，通常是把 PowerShell 指令貼到 CMD。先看提示字元：PS C:\Users\...> 是 PowerShell，沒有 PS 的 C:\Users\...> 多半是 CMD。
裝完後開一個新的 terminal，進到專案資料夾，跑：
claude --version
claude doctor
claudeclaude 會帶你走瀏覽器登入。Anthropic 文件說 Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳號；免費 Claude.ai 方案不含 Claude Code。公司環境如果有 proxy、SSO 或安全閘道，登入錯誤先查網路與組織設定，不要急著重裝。
路線 B：WSL2 內安裝
如果 repo 會用 Bash、Linux 套件、Docker、Makefile、ripgrep、MCP server 或需要比較接近 macOS/Linux 的環境，WSL2 通常比較好維護。Microsoft 文件寫明，Windows 10 2004 以上或 Windows 11 可用 wsl --install 安裝 WSL；Anthropic setup 文件也把 WSL2 列為可用 sandbox 與 Linux toolchain 的路線。
在系統管理員 PowerShell 裡先裝 WSL：
wsl --install重開機並建立 Ubuntu 使用者後，進到 Ubuntu 終端機，在 WSL 裡執行 Linux 安裝指令：
curl -fsSL https://claude.ai/install.sh | bash如果改用 npm，請先確認 Node.js 版本。Anthropic setup 文件與 npm package metadata 顯示，@anthropic-ai/claude-code npm package 目前要求 Node.js 22+，並透過平台相依的 optional dependency 安裝 native binary。
node --version
npm install -g @anthropic-ai/claude-code
claude --version
claude doctorWSL 路線最重要的習慣，是把正式 repo 放在 Linux 檔案系統，例如 ~/projects/my-repo，而不是 /mnt/c/Users/.../OneDrive/...。Anthropic troubleshooting 文件提到，WSL 跨檔案系統讀取會讓搜尋變慢或結果不完整；如果已經遇到這種問題，先把 repo 移到 WSL 的 /home，再重跑 claude doctor 和一次真實搜尋任務。
VS Code、Cursor 與終端機怎麼接
VS Code 的 WSL extension 讓 Windows 版 VS Code 直接打開 WSL 裡的資料夾，保留 Windows 桌面體驗，同時使用 Linux 工具鏈。安裝後，建議從 WSL 內進專案再開編輯器：
cd ~/projects/my-repo
code .左下角看到 WSL: Ubuntu，代表目前是 Remote-WSL 環境。Cursor 也能用類似方式接 WSL，但不要同時在 Windows 路徑和 WSL 路徑各開一份同一個 repo；最容易出現行尾、檔案鎖定與同步衝突。
原生 Windows 路線則建議裝 Git for Windows。若 Claude Code 找不到 Git Bash，可在設定裡指定 CLAUDE_CODE_GIT_BASH_PATH。公司環境如果不允許 Git Bash，就先用 PowerShell tool，並把會修改檔案或跑部署的命令留給人工確認。
安裝後用一個低風險任務驗收
不要只停在 claude --version。真正的驗收，是確認 Claude Code 能在你選的環境裡讀專案、提出計畫、改一個低風險檔案、跑測試，並把證據交給你人工檢查。
第一次任務可以這樣做：
請先讀這個 repo 的 README、package.json 與測試設定，整理專案用途、主要指令、低風險入門任務。不要改檔，先列計畫和你需要我確認的地方。如果這一步順利，再挑一個可回滾的小任務，例如修 README、補一個測試、調整小型錯字或整理一段 release note。要求它先說會改哪些檔案，再改檔、跑測試、回報命令輸出。這樣做可以同時驗收 shell、檔案讀寫、權限提示、測試流程與人工檢查節奏。
Windows 常見錯誤怎麼分流
一、claude 找不到。先關掉 terminal 重開，再跑 where.exe claude 或在 WSL 裡跑 which claude。如果是 npm 安裝，檢查 npm global bin 是否在 PATH；如果是 WSL 安裝，請在 WSL 終端機內使用，不要回 PowerShell 找它。
二、PowerShell/CMD 指令報語法錯。回到上一節確認自己在哪個 shell。PowerShell 用 irm ... | iex，CMD 用 curl ... && install.cmd，兩者不要混用。
三、Git Bash 或 Bash tool 找不到。原生 Windows 可以裝 Git for Windows；若已安裝但 Claude Code 找不到，依官方 setup 文件指定 CLAUDE_CODE_GIT_BASH_PATH。若公司不允許 Git Bash，就接受 PowerShell tool 路線，並避免直接執行只支援 Bash 的腳本。
四、WSL 裡搜尋慢、讀不到完整結果。把 repo 從 /mnt/c/、OneDrive、Dropbox、iCloud 或中文路徑搬到 ~/projects/。跨檔案系統開發會讓 WSL 檔案掃描變慢，也容易讓 editor、git 和同步工具互相搶檔。
五、npm 安裝警告 Node 版本。@anthropic-ai/claude-code npm package 目前要求 Node.js 22+。如果只是想最少踩坑，優先用官方 native installer；若團隊標準是 npm，先升 Node，再用 npm install -g @anthropic-ai/claude-code@latest 更新，不要用 sudo npm install -g 硬解權限。
六、登入或 OAuth 卡住。先確認帳號方案是否支援 Claude Code，再看公司 proxy、VPN、DNS、瀏覽器跳轉與組織權限。能開 claude.ai 不代表 terminal 的登入流程一定能通過公司網路。
什麼情況不要硬裝
如果你只是想在 IDE 裡補全一兩行程式，Cursor、Copilot 或一般 Claude 對話通常更快。若公司 repo 裡有正式環境 secrets、資料庫權限或部署腳本，請先整理權限、測試與人工檢查流程，不要把安裝成功當成可以直接放手。
如果 Windows 電腦 RAM 很少、WSL2 被公司政策禁止、或團隊沒有任何人能維護 Linux 開發環境，先走原生 Windows。反過來，如果團隊已經用 Docker、Makefile、Bash script 和 Linux CI，硬把 Claude Code 放在 Windows 路徑裡，後面通常會在檔案系統與 shell 差異上花更多時間。
來源與延伸閱讀
- Anthropic：Claude Code overview
- Anthropic：Claude Code advanced setup
- Anthropic：Claude Code troubleshooting
- npm：@anthropic-ai/claude-code
- Microsoft Learn：安裝 WSL
- Visual Studio Marketplace：WSL extension
FAQ
2026 年 Windows 還需要 WSL2 嗎？
不一定。Anthropic 已支援原生 Windows、PowerShell、CMD 與 WinGet。專案如果主要在 Windows 工具鏈裡，原生路線比較直接；如果專案依賴 Linux 指令、容器、sandbox 或 WSL 裡的 repo，WSL2 仍然比較穩。
Claude Code 可以用免費 Claude.ai 帳號嗎？
不行。Anthropic setup 文件寫明，Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳號；也可走部分第三方 API provider。免費 Claude.ai 方案不含 Claude Code access。
WSL2 裡的 repo 要放在哪裡？
正式開發建議放在 WSL 的 Linux 檔案系統，例如 ~/projects/my-repo。不要把主要 repo 放在 /mnt/c/Users/.../OneDrive/...，那會讓檔案搜尋、git、editor 和同步工具更容易變慢或衝突。
安裝成功後第一件事要做什麼？
先跑 claude --version、claude doctor，再登入並請 Claude Code 只讀 repo、整理專案與低風險任務，不要立刻改檔。等讀檔、計畫、權限提示都正常，再讓它處理一個可回滾的小任務。