知識極客電子報
· 7 min read

Windows 系統完整安裝 Claude Code 詳細指南

系統需求檢查

基本需求

檢查你的 Windows 版本

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

檢查虛擬化是否啟用

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

步驟 1：啟用 WSL 功能

方法 A：自動安裝（推薦）

  1. 以管理員身份開啟 PowerShell：
    • 在開始功能表搜尋「PowerShell」
    • 右鍵點擊「Windows PowerShell」
    • 選擇「以系統管理員身分執行」
  2. 重新開機： 這個指令會啟用執行 WSL 所需的功能並安裝 Ubuntu 發行版

執行安裝指令：

wsl --install

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

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

  1. 重新開機
  2. 下載並安裝 WSL2 Linux 核心更新套件：

設定 WSL2 為預設版本：

wsl --set-default-version 2

啟用虛擬機器平台：

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

啟用 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. 點擊「取得」進行安裝

方法 B：透過指令列

wsl --install -d Ubuntu

驗證安裝

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

wsl -l -v

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

  NAME      STATE           VERSION
* Ubuntu    Running         2

步驟 3：配置 Ubuntu

首次啟動 Ubuntu

  1. 啟動 Ubuntu：
    • 在開始功能表搜尋「Ubuntu」
    • 點擊啟動
  2. 建立使用者帳號：
    • 輸入使用者名稱（建議使用英文，不要有空格）
    • 設定密碼（輸入時不會顯示，這是正常的）
    • 重複輸入密碼確認

更新系統套件

sudo apt update && sudo apt upgrade -y

安裝必要的開發工具

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

步驟 4：安裝 Node.js

方法 A：使用 NVM（推薦）

建議使用 Node Version Manager (NVM)，這樣每個專案都可以固定自己的 Node 版本：

驗證安裝：

node -v && npm -v

安裝最新的 LTS Node.js：

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

驗證 NVM 安裝：

nvm --version

重新載入 Shell 配置：

source ~/.bashrc

或者重新開啟終端機

安裝 NVM：

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

方法 B：使用 NodeSource Repository

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

步驟 5：配置 npm 全域目錄

為避免權限問題，需要設定使用者層級的 npm 全域目錄：

驗證配置：

npm config get prefix

應該顯示：/home/你的使用者名稱/.npm-global

更新 PATH 環境變數：

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

配置 npm 使用新目錄：

npm config set prefix ~/.npm-global

建立全域目錄：

mkdir -p ~/.npm-global

步驟 6：安裝 Claude Code

基本安裝

Claude Code 是作為 npm 套件發布的：

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

如果遇到平台檢測問題

有時 WSL 可能仍在檢測 Windows 環境，請嘗試：

npm config set os linux
npm install -g @anthropic-ai/claude-code --force --no-os-check

驗證安裝

檢查版本：

claude --version

檢查安裝狀態：

claude doctor

步驟 7：設定帳號和身份驗證

準備工作：設定付費方案

在使用 Claude Code 之前，你需要設定付費方案：

  1. 前往 Anthropic Console
  2. 註冊或登入帳號
  3. 前往「Billing」頁面設定付費方案

初始化和身份驗證

  1. 選擇身份驗證方式：選項 A：Anthropic Console（預設）選項 B：Claude App (Pro 或 Max 方案)
    • 透過 Anthropic Console 完成 OAuth 流程
    • 需要在 console.anthropic.com 設定付費方案
    • 訂閱 Claude 的 Pro 或 Max 方案
    • 提供統一訂閱，包含 Claude Code 和網頁介面
  2. 完成 OAuth 流程：
    • 系統會開啟瀏覽器
    • 登入你的帳號
    • 授權 Claude Code 存取

啟動 Claude Code：

claude

導航到你的專案目錄：

cd ~/your-project-directory

步驟 8：初始化專案

建立專案指南

提交生成的檔案：

git add CLAUDE.md
git commit -m "Add Claude Code project guide"

生成專案指南：

claude "Generate a CLAUDE.md project guide for this directory"

執行簡單指令測試：

claude "Hello, can you help me with coding?"

步驟 9：效能優化

WSL 效能配置

在你的 Windows 使用者目錄中建立 .wslconfig 檔案：

重新啟動 WSL：

wsl --shutdown

加入以下配置：

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

開啟記事本：

notepad %USERPROFILE%\.wslconfig

終端機優化

支援的 Shell：

設定 Option+Enter 換行：

在你的 ~/.bashrc 或 ~/.zshrc 中加入：

# 啟用 Meta 鍵支援
bind '"\e\r": "\n"'

常見問題和解決方案

問題 1：「Claude Code is not supported on Windows」

原因：系統仍在檢測 Windows 環境變數

解決方案：

  1. 確保在 WSL 終端機中執行，不是 PowerShell 或 CMD

如果路徑不對，重新安裝 Node.js：

# 移除可能的 Windows Node.js 參考
export PATH=$(echo $PATH | tr ':' '\n' | grep -v '/mnt/c' | tr '\n' ':' | sed 's/:$//')
# 重新安裝 Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

檢查是否使用 Linux 版本的 Node.js：

which node
which npm

應該顯示 /usr/ 或 /home/ 開頭的路徑，不是 /mnt/c/

問題 2：權限錯誤

錯誤訊息：EACCES: permission denied

解決方案：

重新配置 npm：

npm config set prefix ~/.npm-global
npm config list

清理失敗的安裝：

# 如果曾在 Windows 目錄安裝失敗
sudo rm -rf /mnt/c/Users/[你的使用者名稱]/AppData/Roaming/npm/node_modules/@anthropic-ai/claude-code

# 如果曾在 Linux 目錄安裝失敗
sudo rm -rf /usr/lib/node_modules/@anthropic-ai/claude-code

不要使用 sudo：

# 錯誤做法
sudo npm install -g @anthropic-ai/claude-code

# 正確做法
npm install -g @anthropic-ai/claude-code

問題 3：找不到 bash

錯誤訊息：spawn /bin/bash ENOENT

解決方案：

設定預設 Shell：

chsh -s /bin/bash

如果 bash 不存在：

sudo apt install bash

確認 bash 已安裝：

which bash
ls -la /bin/bash

問題 4：無法與 Claude Code 介面互動

症狀：UI 出現但無法互動，指令被底層 shell 處理

解決方案：

  1. 嘗試不同的終端機：
    • Windows Terminal（推薦）
    • 原生 Ubuntu 終端機

更新終端機配置：

export TERM=xterm-256color

檢查終端機支援：

echo $TERM

問題 5：安裝緩慢或失敗

解決方案：

增加 npm 逾時時間：

npm config set timeout 600000

清除 npm 快取：

npm cache clean --force

更換 npm registry：

npm config set registry https://registry.npmjs.org/

進階配置

設定 Git（如果還沒設定）

git config --global user.name "你的名稱"
git config --global user.email "你的email@example.com"

安裝額外的實用工具

# 安裝 ripgrep（Claude Code 使用的搜尋工具）
sudo apt install ripgrep

# 安裝其他實用工具
sudo apt install tree htop neofetch

設定 Windows Terminal 整合

  1. 安裝 Windows Terminal（如果還沒有）
  2. 設定 Ubuntu 為預設設定檔：
    • 開啟 Windows Terminal
    • 點擊下拉箭頭 → 設定
    • 將 Ubuntu 設為預設設定檔

驗證完整安裝

執行以下指令確認一切正常：

# 檢查系統資訊
uname -a

# 檢查 Node.js 和 npm
node -v && npm -v

# 檢查 Claude Code
claude doctor

# 檢查 Git
git --version

# 測試 Claude Code
claude "Write a simple hello world function in Python"

開始使用

安裝完成後，你可以：

  1. 瀏覽到任何專案目錄
  2. 執行 claude 啟動
  3. 開始與 AI 編程助手互動

常用指令

# 啟動 Claude Code
claude

# 檢查系統狀態
claude doctor

# 配置設定
claude config

# 更新 Claude Code
claude migrate-installer  # 如果使用新的安裝方法

# 終端機設定
claude terminal-setup  # 配置快捷鍵

額外資源

安裝完成後，你就可以在 Windows 系統上享受強大的 AI 程式設計助手了！如果遇到任何問題，請參考上述故障排除指南或查閱官方文件。

Share Share Share Share Share Email