Claude Code Windows 安裝完整指南 2026：原生 vs WSL2 + 15 個踩坑全解

為什麼 2025 年的安裝文不夠用？

我把繁中 SERP 上「Claude Code Windows 安裝」翻了一輪，90% 是 2025 年寫的**:

1. 過時版:「必須裝 WSL2」——但 2026 年 Anthropic 已釋出 Windows 原生版
2. 單一視角:只寫 WSL2 或只寫原生,沒人並列 + 給決策樹
3. 踩坑不夠:FAQ 只列 3-5 題,真實踩坑 15+ 個
4. 零台灣特化:沒人寫中文路徑、OneDrive、台灣 DNS 攔截 OAuth 等獨有痛點

這篇是 2026/05 版本，寫給 Windows 用戶 + 含完整決策樹 + 15 個踩坑 + 台灣特化。

🎯 30 秒決策樹：原生還是 WSL2?

你是 Windows 用戶?
  ├── 是
  │   ├── 公司 / IT 部禁止裝 WSL2 嗎?
  │   │   ├── 是 → 選「**原生 Windows**」**(路徑 A)
  │   │   └── 否 → 繼續
  │   ├── 你之前用過 Linux 終端機嗎?(WSL / VS Code Remote / 雲端開發)
  │   │   ├── 是 → 選「**WSL2**」**(路徑 B,推薦)
  │   │   └── 否 → 繼續
  │   ├── 你的專案多數是 Node / Python / Go 嗎?
  │   │   ├── 是 → 選「**WSL2**」**(體驗最佳)
  │   │   └── 否 → 選「**原生 Windows**」**(快速上手)
  │   └── 預期會搭配 VS Code 或 Cursor 嗎?
  │       ├── 是 → 選「**WSL2 + Remote-WSL 擴充**」**
  │       └── 否 → 都可,看上面結果
  └── macOS / Linux → [回主指南](/tools/claude-code/)

Mason 推薦:8 成讀者選 WSL2——體驗跟 macOS / Linux 一致 + 未來幾年 Anthropic 主力支援的環境。

2 成讀者選原生:

• 企業 Windows 不能裝 WSL2(IT 政策)
• 完全不想學 Linux——願意接受部分功能限制
• 電腦記憶體 < 8 GB(WSL2 跑起來會卡)

🚀 路徑 A：原生 Windows 安裝（2 分鐘）

系統需求

• Windows 10 21H2 / Windows 11 22H2 以上
• 8 GB+ 記憶體（建議 16 GB）
• 5 GB 磁碟空間
• PowerShell 5.1+(Windows 內建)

PowerShell 一行安裝

# 以「**系統管理員**」**身分開啟 PowerShell
iwr -useb https://claude.ai/install-windows.ps1 | iex

裝完後:

claude --version    # 應顯示版本號
claude doctor       # 環境檢查

第一次登入

claude
# 自動開瀏覽器 → Anthropic OAuth → 登入 Claude Pro / Max 帳號

已知限制（選原生你要接受的）

🐧 路徑 B:WSL2 完整安裝（10 分鐘，推薦）

為什麼選 WSL2

3 個壓倒性優勢:

1. 跟 macOS / Linux 用戶體驗一致——社群教學 99% 適用
2. 完整 sandbox——Bash 指令隔離，Windows 主環境不會被汙染
3. MCP / 開源工具 100% 相容——未來擴充無限制

啟用 WSL2（以系統管理員身分）

# Windows PowerShell (系統管理員)
wsl --install

# 重開機後,Start Menu 會出現 Ubuntu (預設 22.04 LTS)

選 Ubuntu 22.04 LTS——最穩定、社群支援最完整。

在 WSL Ubuntu 內安裝 Node.js + Claude Code

開啟 Ubuntu:

# 1. 更新 apt
sudo apt update && sudo apt upgrade -y

# 2. 裝 NVM (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# 3. 裝 Node.js LTS
nvm install --lts
nvm use --lts

# 4. 裝 Claude Code
npm install -g @anthropic-ai/claude-code

# 5. 驗證
claude --version

第一次登入(OAuth in browser)

claude
# 自動產生 URL → 複製到 Windows 瀏覽器 → OAuth 登入 → 自動回到 WSL

VS Code Remote-WSL 連接

1. Windows 安裝 VS Code（主機側）
2. VS Code 裝擴充：Remote - WSL（微軟官方）
3. 在 WSL Ubuntu 內:code . → VS Code 開 WSL 環境
4. VS Code Terminal 預設改成 WSL Ubuntu

詳細配置見下方第 6 節。

⚠️ 15 個 Windows 用戶踩坑全解（差異化招牌）

1. claude is not recognized as cmdlet (PATH 問題)

症狀:裝完原生版，PowerShell 找不到 claude。

為什麼:安裝路徑沒加進 PATH 環境變數。

解法:

# 找出 claude.exe 位置
where.exe claude
# 通常在 C:\Users\<你>\AppData\Roaming\Anthropic\Claude\

# 加進 PATH
$env:PATH += ";C:\Users\<你>\AppData\Roaming\Anthropic\Claude\"
# 永久加進去 (系統環境變數設定)

2. WSL 找不到指令

症狀:wsl --install 報「Windows 找不到」**。

為什麼:Windows 版本太舊——必須 Windows 10 21H2+ 或 Win 11。

解法:

• Windows Update 升級到最新
• 或手動下載 WSL Kernel + 開啟「虛擬機器平台」**功能

3. 安裝卡在 npm 權限

症狀:npm install -g 報 EACCES 權限錯誤。

為什麼:npm 預設裝到系統目錄，需 root 權限**。

解法:改 npm prefix 到家目錄——最佳實踐:

# 設定 npm 全域目錄到 ~/.npm-global
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# 加進 ~/.bashrc
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 重新安裝
npm install -g @anthropic-ai/claude-code

4. WSL2 啟動慢

症狀:Ubuntu 啟動要 30 秒以上,RAM 用太多。

為什麼:WSL2 預設可用整個 Windows RAM,且沒最佳化。

解法:用 .wslconfig 限制資源——在 Windows 家目錄建 C:\Users\<你>\.wslconfig:

[wsl2]
memory=6GB
processors=4
swap=8GB
localhostForwarding=true

重啟 WSL:wsl --shutdown → 再開 Ubuntu。

5. 中文路徑亂碼

症狀:檔案放在「C:\使用者\Mason\專案**」,Claude Code 讀檔報「檔案不存在」或亂碼**。

為什麼:WSL2 對中文路徑支援差——Linux 系統習慣 ASCII 路徑。

解法 1:搬出中文路徑——最徹底

# WSL 內
mkdir -p ~/projects
mv /mnt/c/Users/Mason/專案/* ~/projects/

解法 2:切到 UTF-8 locale（部分情況有效）

echo "export LANG=zh_TW.UTF-8" >> ~/.bashrc
echo "export LC_ALL=zh_TW.UTF-8" >> ~/.bashrc
source ~/.bashrc

Mason 強烈建議:Windows 安裝時用英文使用者名稱——避免後續所有跨工具問題。

6. OneDrive 同步衝突

症狀:專案放在 C:\Users\<你>\OneDrive\專案\,Claude Code 改檔 + OneDrive 同步 = 檔案被 OneDrive 鎖定 / 衝突 / 版本錯亂。

為什麼:OneDrive 即時同步機制跟 git / Claude Code 的 file watch 衝突。

解法:專案搬出 OneDrive——git 已是版本控制，不需要 OneDrive 同步**:

# Windows PowerShell
Move-Item "C:\Users\Mason\OneDrive\專案" "C:\Users\Mason\Projects"
# WSL 內讀取改成 /mnt/c/Users/Mason/Projects/
# 或更佳:搬到 ~/projects/ (WSL 內部)

7. Docker Desktop 衝突

症狀:Docker Desktop 跟 WSL2 互搶資源,或 Docker 改用 Hyper-V 後 WSL2 出問題。

為什麼:Docker Desktop 預設用 WSL2 backend——設定衝突會引發雙方問題。

解法:確認 Docker Desktop 用 WSL2 backend:

• Docker Desktop → Settings → General → 勾「Use the WSL 2 based engine」
• Resources → WSL Integration → 勾你的 Ubuntu distro

8. /mnt/c/ vs ~/projects/ 哪個快？

症狀:專案放在 /mnt/c/(Windows 磁碟),WSL 讀寫慢 3-5 倍。

為什麼:WSL2 跨檔案系統存取(NTFS ↔ ext4)有額外開銷。

解法:重要專案放 ~/projects/(WSL 內部 ext4)——速度跟原生 Linux 一致。

例外:需要 Windows 軟體存取的檔案（例如 Photoshop / Excel）才放 /mnt/c/。

9. claude --version 顯示舊版

症狀:裝了新版，但 claude --version 仍顯示舊版號**。

為什麼:有多個版本 或 快取問題。

解法:

# WSL Ubuntu
npm update -g @anthropic-ai/claude-code
# 或完整重裝
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

10. VS Code 在 Windows 開 WSL2 檔案

症狀:用 Windows VS Code 直接開 \\wsl$\Ubuntu\home\<你>\projects\ 路徑,改檔後 WSL 內看到衝突。

為什麼:Windows VS Code 跨檔案系統存取——檔案編碼、行尾符號可能轉換錯誤。

解法:改用 Remote-WSL 擴充——VS Code「連到」WSL Ubuntu**:

1. WSL Ubuntu 內輸入 code . → 自動開 VS Code Remote-WSL
2. 左下角顯示「WSL: Ubuntu」**= 成功

11. 防毒軟體攔截 npm

症狀:npm install 卡住 / 報「權限拒絕」**。

為什麼:Windows Defender 或第三方防毒將 npm 下載判定為可疑檔案。

解法:

• 加 Node.js / npm 到防毒白名單
• 加 WSL Ubuntu 整個資料夾到白名單:C:\Users\<你>\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu_*

12. 公司 Proxy 環境

症狀:公司網路有 Proxy,npm install 失敗或登入卡住。

解法:

# 設定 npm proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# 環境變數
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

13. Cursor 跟 Claude Code 衝突

症狀:Cursor 跟 Claude Code 都裝了，互相搶資源 / 配置打架**。

為什麼:兩者都用 VS Code 核心——設定可能衝突。

解法:各自獨立——Cursor 開 Cursor,Claude Code 開 WSL 終端機——不要在 Cursor 內裝 Claude Code 擴充**。

詳細對比 → Claude Code vs Cursor 30 天深度對比

14. claude doctor 報 git 找不到

症狀:WSL Ubuntu 內 claude doctor 報「git not found」。

為什麼:Ubuntu 預設可能沒裝 git。

解法:

sudo apt install -y git

15. 訂閱登入後一直失敗

症狀:OAuth 完成，但 Claude Code 報「未授權」**。

為什麼:~/.claude/credentials 快取衝突——舊登入未清理。

解法:

rm -rf ~/.claude/credentials
claude  # 重新走 OAuth

🇹🇼 台灣 Windows 用戶獨有痛點

1. 中文使用者名稱 / 中文路徑

問題:Windows 帳號是中文,家目錄是「C:\使用者\王小明」——WSL2 跟 Claude Code 都會出問題。

解法:

• 新裝 Windows → 永遠用英文使用者名稱
• 已是中文 → 新建英文帳號 + 設為管理員 + 改用英文帳號操作
• 暫時 → 用 ~/projects/(WSL 內部) 避開所有中文路徑

2. OneDrive / iCloud 雲端同步衝突

問題:Windows 預設新建專案在 OneDrive 路徑——Claude Code 改檔 + OneDrive 同步 = 衝突。

解法:

• OneDrive 設定 → 移除「桌面 / 文件 / 圖片」自動同步**
• 重要專案放 ~/projects/(WSL 內部) 或 C:\Projects\（避開 OneDrive）

3. 中華電信 / 台哥大 DNS 偶爾解析 OAuth 失敗

問題:Claude Code OAuth 偶爾報「Cloudflare 解析失敗」。

為什麼:台灣 ISP 的 DNS 偶爾過慢 / Anthropic Cloudflare 在台灣節點抖動。

解法:切到 Cloudflare 1.1.1.1 或 Google 8.8.8.8:

• Windows 網路設定 → 變更介面卡選項 → 右鍵連線 → 內容 → IPv4 → DNS
• 改成 1.1.1.1 / 1.0.0.1 或 8.8.8.8 / 8.8.4.4

4. 繁中 IME 在 WSL2 終端機

問題:WSL Ubuntu 終端機輸入繁中會卡 / 顯示異常。

解法:使用 Windows Terminal（預裝在 Win 11）:

• Windows Terminal → 設定 → Ubuntu 預設值 → 字型 → 選「標楷體 / 微軟正黑體」
• 或裝 Noto Sans Mono CJK TC 中文等寬字型

🛠️ VS Code / Cursor + WSL2 完整配置

Remote-WSL 擴充安裝

VS Code(Windows 主機側):

1. 開 VS Code → 擴充市集
2. 搜「Remote - WSL」**→ Microsoft 官方 → 安裝
3. 重啟 VS Code

Cursor 也支援——同樣步驟（Cursor 內擴充市集搜 Remote - WSL）。

進入 WSL 環境

從 Ubuntu 端:

cd ~/projects/my-project
code .
# VS Code 自動開 Remote-WSL 模式

或從 VS Code:左下角 >< 圖示 → Connect to WSL → 選 Ubuntu

settings.json 配置範本

把以下放到 VS Code 的 WSL 端 settings.json(Ctrl+Shift+P → “Preferences: Open Settings (JSON)”):

{
  "terminal.integrated.defaultProfile.linux": "bash",
  "terminal.integrated.profiles.linux": {
    "bash": {
      "path": "bash"
    }
  },
  "files.eol": "\n",
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 2000,
  "editor.formatOnSave": true,
  "remote.WSL.fileWatcher.polling": false
}

Terminal 預設改 WSL Ubuntu

Windows Terminal:

1. 開 Windows Terminal → 設定
2. 啟動 → 預設設定檔 → Ubuntu

VS Code Terminal:

• 自動繼承上面 settings.json 的設定

⚡ WSL2 效能調校 5 條

1. 專案放 ~/projects/，不放 /mnt/c/

速度差 3-5 倍——上面踩坑 8 已詳述。

2. .wslconfig 設定 memory / processors

避免 WSL2 吃光 RAM——見踩坑 4 範例。

3. WSL 2 backend for Docker

Docker Desktop 用 WSL2 後端——見踩坑 7 範例。

4. .wslconfig 加 networkingMode(Win 11+)

[wsl2]
networkingMode=mirrored

讓 WSL2 跟 Windows 共用網路設定——避免 OAuth / VPN 衝突。

5. 關閉不需要的 systemd 服務

# 在 WSL Ubuntu 內
systemctl list-unit-files --type=service --state=enabled
# 關掉用不到的(例如 snapd、cups)
sudo systemctl disable snapd
sudo systemctl disable cups

省 200-500 MB RAM。

🎉 第一個任務：確認都 work

裝完後，立刻試一個任務確認都 work:

# WSL Ubuntu 內
cd ~/projects/test-project  # 任何專案
claude
> 請讀這個專案,給我 5 分鐘的高層概覽(技術棧、主要功能、潛在問題)

Claude Code 會自動:

1. 掃描專案結構
2. 讀 README、package.json、主要程式碼檔
3. 給你結構化的專案總覽

這是「第一次驚艷」的時刻**——你沒寫一行程式碼，Claude 已經幫你建立了專案心智模型。

❓ FAQ

# C:\Users\<你>\.wslconfig
[wsl2]
memory=6GB
processors=4
swap=8GB

⚠️ 警語

• 本文基於 2026/05 資訊——Claude Code、WSL2、Windows 都在持續更新,細節可能變動
• 企業環境裝 WSL2 前 → 跟 IT 部確認政策——部分公司禁止使用者開 WSL2
• 跨多台 Windows 工作 → 建議用同一個帳號名 + 統一專案路徑——避免每台都重新配置

權威來源:

• Claude Code 官方文件
• WSL2 微軟官方安裝
• VS Code Remote-WSL 擴充

深入閱讀:➜ Claude Code 完全 Pillar | Claude Code 新手入門 | Claude Code 工作流完整實戰