# Claude Code 完整安裝指南 (Windows)

## 系統需求檢查

### 基本需求

* **作業系統**：Windows 10 版本 2004 以上（組建 19041 以上）或 Windows 11
* **硬體**：最少 4GB RAM，建議 8GB 以上
* **網路**：穩定的網路連線（用於身份驗證和 AI 處理）
* **權限**：系統管理員權限
* **虛擬化支援**：電腦必須支援虛擬化功能，且需在 BIOS 中啟用

### 檢查你的 Windows 版本

1. 按 `Windows` 鍵 + `R`
2. 輸入 `winver` 並按 Enter
3. 確認版本符合需求

### 檢查虛擬化是否啟用

1. 開啟工作管理員 (`Ctrl` + `Shift` + `Esc`)
2. 點擊「效能」標籤
3. 選擇「CPU」
4. 確認「虛擬化」顯示為「已啟用」

**若虛擬化未開啟**：
重新啟動電腦並進入 BIOS/UEFI 設定，各家設定的詳細位置請搜尋文件，或是查看 YouTube 會有較詳細的說明。

---

## 步驟 1：啟用 WSL 功能

### 方法 A：自動安裝

1. **以管理員身份開啟 PowerShell**：
* 在開始功能表搜尋「PowerShell」
* 右鍵點擊「Windows PowerShell」
* 選擇「以系統管理員身分執行」

2. **執行安裝指令**：

wsl --install

* 執行無誤後重新開機，這個指令會啟用執行 WSL 所需的功能並安裝 Ubuntu 發行版。

3. **驗證安裝**：
重新開機後於 PowerShell 內輸入：

wsl --list --verbose

如果看到已安裝的 Linux 發行版和版本資訊，就表示安裝成功。

> **注意**：如果方法 A 成功了，就不用做方法 B。只有在方法 A 失敗或無法執行時，才需要使用方法 B。

### 方法 B：手動安裝（適用於舊版本或企業環境）

如果自動安裝失敗，請按照以下步驟：

1. 重新開機
2. **下載並安裝 WSL2 Linux 核心更新套件**：
* 前往 Microsoft 官方下載頁面
* 下載並執行安裝程式

3. **設定 WSL2 為預設版本**：

wsl --set-default-version 2

4. **啟用虛擬機器平台**：

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

5. **啟用 WSL 功能**：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

---

## 步驟 2：安裝 Ubuntu

### 方法 A：透過 Microsoft Store

1. 開啟 Microsoft Store
2. 搜尋「Ubuntu」
3. 選擇「Ubuntu 22.04.3 LTS」或最新版本
4. 點擊「取得」進行安裝

### 驗證安裝

於 PowerShell 執行以下指令檢查已安裝的發行版：

wsl -l -v

應該看到類似以下的輸出：

  NAME      STATE           VERSION
* Ubuntu    Running         2

---

## 步驟 3：配置 Ubuntu

### 首次啟動 Ubuntu

1. **啟動 Ubuntu**：
* 在開始功能表搜尋「Ubuntu」
* 點擊啟動

2. **建立使用者帳號**：
* 輸入使用者名稱（建議使用英文，不要有空格）
* 設定密碼（輸入時不會顯示，這是正常的）
* 重複輸入密碼確認

### 更新系統套件

此時的位置於 Ubuntu 的視窗內：

sudo apt update && sudo apt upgrade -y

### 安裝必要的開發工具

sudo apt install build-essential curl git wget unzip -y

---

## 步驟 4：讓 VS Code 預設進入 WSL

1. 開啟 VS Code，打開終端機（若沒有下載安裝 VS Code 可以查看 VS Code 安裝教學）。

3. 預設的終端機是 PowerShell。
4. 點擊終端機視窗右側往下的箭頭。

6. 選擇 **Default Profile**。
7. 選擇 **Ubuntu WSL**。
8. 按下加號新增終端機。
9. 這時啟動的新終端機就會是 WSL。

### 步驟 4 - 發生錯誤時

如果進行步驟 4 發現啟動有錯誤，很可能是 VS Code 預設把 `bash.exe` 當作啟動 WSL 的觸發點。我們只要改成 `wsl.exe` 就可以解決這個問題。

**第 1 步：打開 `settings.json**`

* 在最上方選單列找到「檔案」
* 點擊「檔案」→「喜好設定」→「設定」
* 畫面右上角會有一個像文件頁面的圖示，游標移上去會顯示「開啟設定 (JSON)」
* 點擊這個圖示，VS Code 會開啟 `settings.json` 檔案

**第 2 步：修改設定**
在 `settings.json` 中，找到目前設定的區塊，可能長這樣：

"Ubuntu (WSL)": {
  "path": "C:\\Windows\\System32\\bash.exe",
  "args": [
    "-d",
    "Ubuntu"
  ]
}

把 `bash.exe` 改成 `wsl.exe`：

"Ubuntu (WSL)": {
  "path": "C:\\Windows\\System32\\wsl.exe",
  "args": [
    "-d",
    "Ubuntu"
  ]
}

**第 3 步：設定為預設終端機**
在同一份 `settings.json` 裡，確認有以下設定：

"terminal.integrated.defaultProfile.windows": "Ubuntu (WSL)"

**第 4 步：測試**

* 儲存 `settings.json`
* 在選單列點擊「終端機」→「新增終端機」
* 如果終端機顯示像這樣 `username@DESKTOP:/mnt/c/Users/你的帳號$`，就代表成功用 `wsl.exe` 啟動 WSL。

---

## 步驟 5：建立 Linux 的乾淨路徑

### 步驟 5.1 檢驗你的環境是否乾淨

在 WSL 環境內輸入：

which npm
which node

* **狀況 1：完全乾淨**
如果你輸入 `which npm` 與 `which node`，輸入完的是緊鄰的狀態（沒有輸出路徑），代表你的環境完全乾淨，直接進入 **步驟 6** 即可。
* **狀況 2：輸入出現的路徑是 `/mnt/c/**`
如果你過去有自行在網路上安裝過 Node.js，那麼當你輸入 `which npm` 或是 `which node` 之後，下一行會出現 `/mnt/c/` 開頭的資訊，代表你的環境需要進行清理。
> 路徑的出現的位置，會在你輸入指令的下一行，如果沒有出現路徑，代表你的環境是乾淨的。

**請繼續執行下面的步驟 5.2**。

### 步驟 5.2 將你的環境設定的乾淨（如果 5.1 的結果顯示 /mnt/c/ 才需要）

**為什麼需要建立乾淨路徑？**
在 WSL 中執行 `npm` 時，可能誤用 Windows 版 `npm`，目標是讓 WSL 僅呼叫 Ubuntu（Linux）內部的 `npm`。

**Step 1 - 停用 Windows 路徑自動附加**
打開 VS Code 開啟終端機（若上個步驟已設定完，將直接進入 WSL 環境）。
輸入以下指令打開設定檔：

sudo nano /etc/wsl.conf

在設定檔案中加入以下兩行：

[interop]
appendWindowsPath = false

編輯完成後按 `Ctrl` + `O` 儲存，之後 `Ctrl` + `X` 結束編輯，接著選擇 `Y` 儲存設定。

**Step 2 - 關閉所有發行版**
儲存後在 PowerShell 中執行（注意：此指令為在 PowerShell 上輸入，並非 WSL 環境）：

wsl --shutdown

接著重新開啟 VS Code 內的終端機，且回到 WSL 環境內。

**Step 3 - 驗證並修正 `$PATH` / 別名**
在 WSL 環境內輸入：

which npm
which node

* 結果應指向 Linux 路徑（例如 `~/.nvm/versions/node/.../bin/npm`），則進行下一步操作。
* 如果位於 `/mnt/c/` 代表是 Windows 的 npm，則需再返回重新設定。

---

## 步驟 6：安裝 NVM 與 Node.js

**以下步驟均在 WSL 環境下執行。**

1. **安裝 NVM**：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

2. **重新載入環境**：
開啟新的終端機視窗。
3. **驗證 NVM 安裝**：

nvm --version

4. **安裝最新的 LTS Node.js**：

nvm install --lts
nvm use --lts
nvm alias default node

---

## 步驟 7：安裝 Claude Code

**以下步驟均在 WSL 環境下執行。**

1. **安裝指令**：

npm install -g @anthropic-ai/claude-code

> **注意事項**：請勿加 `sudo`，以免造成權限與安全風險。

2. **驗證安裝**：

claude doctor

接著啟動 Claude Code 驗證身份後即可使用。

---

## 步驟 8：Claude Code 身份驗證設定

1. **啟動 Claude Code**：
開啟終端機輸入：

claude

2. **設定顯示**：設定一下如何顯示。
3. **驗證帳號**：
* 首次啟動時，Claude Code 會引導你完成一次性的 OAuth 驗證流程。
* 我們使用 **選項 1** 驗證。
* **此時先不要按下確認**。

4. **購買 Pro 方案**：
* 先到 Claude 網頁版找到訂閱，點選 **Pro**。

* 點選一個月方案註冊。

* 購買完後會出現畫面，請不要關閉瀏覽器，回到 VS Code。

5. **完成驗證**：
* 在 VS Code 的選項 1 按下確認。
* 瀏覽器會跳出授權請求，點擊 **授權 (Authorize)**。

* 出現完成畫面就關閉視窗回到 VS Code。
* 出現 `Login successful` 按下 Enter 繼續後續設定。

6. **最終設定**：
* 閱讀安全提醒後按下 Enter 繼續。
* 詢問是否要使用建議的終端機設定，選擇 **1**，啟用建議的終端機設定。
* 到每個新資料夾的時候都會詢問您，選擇 **1**，同意執行。

**恭喜完成！可以使用 Claude Code 了。**