Windows 11 WSL2 完整安裝指南：AI 開發者的 Linux 環境建置

為什麼 AI 開發者需要 WSL2？

如果你是 Windows 使用者，想進入 AI 開發領域，你很快就會發現一個現實：大多數 AI 工具、框架和教學都是以 Linux 為主。PyTorch、TensorFlow、Hugging Face 的官方文件幾乎都假設你在 Linux 或 macOS 環境。

這不是巧合。Linux 擁有以下優勢：

面向	Windows 原生	WSL2 (Linux on Windows)
AI 框架支援	部分支援，常有相容問題	完整支援，與原生 Linux 相同
Docker 效能	較慢，需要 Hyper-V	接近原生 Linux 效能
CUDA 開發	支援但設定複雜	官方原生支援
套件管理	各自為政	apt/pip 統一管理
社群資源	較少	豐富的 Linux 教學資源

WSL2（Windows Subsystem for Linux 2） 讓你在 Windows 上運行完整的 Linux 核心，兼顧兩個世界的優點：Windows 的桌面體驗 + Linux 的開發環境。

┌─────────────────────────────────────────────────────────────┐
│                     Windows 11                               │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Windows    │  │   Windows    │  │    WSL2      │       │
│  │     App      │  │   Terminal   │  │  (Ubuntu)    │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
├─────────────────────────────────────────────────────────────┤
│                    Windows NT 核心                           │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐    │
│  │         輕量化虛擬機（Lightweight Utility VM）        │    │
│  │  ┌─────────────────────────────────────────────┐    │    │
│  │  │            完整 Linux 核心                    │    │    │
│  │  │     （與原生 Linux 完全相容的系統呼叫）        │    │    │
│  │  └─────────────────────────────────────────────┘    │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

圖：WSL2 架構 — 在輕量化虛擬機中運行完整 Linux 核心（參考：Microsoft WSL 文件）

前置條件確認

在開始安裝之前，請確認你的系統符合以下要求：

系統需求

Windows 版本：Windows 10 版本 2004 以上，或 Windows 11（推薦）
系統類型：64 位元
硬體虛擬化：BIOS 中已啟用（大多數電腦預設已啟用）

如何檢查 Windows 版本

按下 Win + R，輸入 winver，按 Enter：

Windows 11 版本 23H2（OS 組建 22631.xxxx）

只要是 Windows 11，或 Windows 10 版本 2004 以上即可。

如何確認硬體虛擬化已啟用

按下 Ctrl + Shift + Esc 開啟工作管理員
點選「效能」分頁
選擇「CPU」
查看右下角「虛擬化」欄位

工作管理員檢查虛擬化狀態 圖：確認「虛擬化」顯示為「已啟用」（來源：Microsoft Community）

如果顯示「已停用」，你需要進入 BIOS 啟用（通常名為 Intel VT-x 或 AMD-V）。

第一部分：WSL2 基礎安裝

步驟 1：以系統管理員身分開啟終端機

按下 Win 鍵，搜尋「終端機」或「Terminal」
右鍵點選「Windows 終端機」
選擇「以系統管理員身分執行」

提示：在搜尋結果中，對「終端機」右鍵點選，選擇「以系統管理員身分執行」。這是安裝 WSL 的必要步驟。

步驟 2：執行 WSL 安裝指令

在終端機中輸入以下指令：

wsl --install

這個指令會自動完成以下工作：

啟用「Windows 子系統 Linux 版」功能
啟用「虛擬機器平台」功能
下載並安裝 WSL2 Linux 核心
下載並安裝 Ubuntu（預設發行版）

WSL 安裝成功畫面 圖：WSL 安裝成功，提示需要重新開機

步驟 3：重新啟動電腦

安裝完成後，系統會提示需要重新開機。請儲存所有工作後重新啟動。

步驟 4：完成 Ubuntu 初始設定

重新開機後，Ubuntu 會自動開啟並要求你設定：

使用者名稱：輸入你想要的 Linux 使用者名稱（小寫字母）
密碼：設定一個密碼（輸入時不會顯示字元，這是正常的）
確認密碼：再輸入一次密碼

Enter new UNIX username: yourname
New password:
Retype new password:
passwd: password updated successfully

注意：這個密碼與 Windows 密碼獨立，請務必記住！

步驟 5：驗證安裝成功

在 Ubuntu 終端機中執行：

# 查看 Linux 版本
cat /etc/os-release

# 查看 WSL 版本
wsl.exe --version

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

PRETTY_NAME="Ubuntu 24.04.1 LTS"
NAME="Ubuntu"
VERSION_ID="24.04"

恭喜！你已經成功安裝 WSL2 和 Ubuntu！

步驟 6：更新系統套件

首次安裝後，建議立即更新所有套件：

# 更新套件清單
sudo apt update

# 升級已安裝的套件
sudo apt upgrade -y

小知識：sudo 代表「以超級使用者權限執行」，系統會要求輸入你剛才設定的密碼。

第二部分：Docker Desktop 整合

Docker 是現代 AI 開發的必備工具。它讓你能夠在隔離的容器中運行應用程式，確保「在我電腦上可以跑」的環境可以完美複製到任何地方。

為什麼要用 Docker + WSL2？

情境	沒有 Docker	有 Docker
安裝 AI 框架	版本衝突、相依性地獄	一個指令拉取預設環境
團隊協作	「在我電腦上可以跑啊」	環境完全一致
部署上線	重新設定生產環境	直接部署容器

步驟 1：下載 Docker Desktop

前往 Docker 官網下載 Windows 版本：

官方下載連結：https://www.docker.com/products/docker-desktop/

下載頁面會自動偵測你的作業系統，點選「Download for Windows」即可。

步驟 2：安裝 Docker Desktop

執行下載的安裝程式
重要：確保勾選「Use WSL 2 instead of Hyper-V」選項
完成安裝後重新啟動電腦

安裝畫面提示：在「Configuration」頁面，務必勾選「Use WSL 2 instead of Hyper-V (recommended)」選項。這將啟用 WSL 2 後端，獲得最佳效能。

步驟 3：設定 WSL 整合

開啟 Docker Desktop
點選右上角齒輪圖示（Settings）
選擇左側「Resources」→「WSL Integration」
啟用「Enable integration with my default WSL distro」
啟用你的 Ubuntu 發行版
點選「Apply & Restart」

設定位置：Settings → Resources → WSL Integration。開啟「Enable integration with my default WSL distro」，並勾選你安裝的 Ubuntu 發行版。

步驟 4：驗證 Docker 運作

開啟 Ubuntu 終端機（從開始選單或在 Windows Terminal 中新增分頁），執行：

# 確認 Docker 已安裝
docker --version

# 執行測試容器
docker run hello-world

如果看到「Hello from Docker!」訊息，代表 Docker 已成功整合 WSL2！

實用範例：運行 Jupyter Lab

讓我們用 Docker 快速啟動一個 AI 開發環境：

# 啟動含有 PyTorch 的 Jupyter Lab
docker run -p 8888:8888 -v $(pwd):/home/jovyan/work jupyter/pytorch-notebook

開啟瀏覽器訪問 http://localhost:8888，你就擁有了一個完整的 AI 開發環境！

第三部分：GPU 與 CUDA 設定

如果你有 NVIDIA 顯示卡，WSL2 可以直接存取 GPU 進行 AI 訓練加速。這是 WSL2 最強大的功能之一。

系統需求

顯示卡：NVIDIA GeForce GTX 1060 以上（建議 RTX 系列）
驅動程式：NVIDIA Game Ready Driver 或 Studio Driver 版本 470.76 以上
Windows 版本：Windows 11，或 Windows 10 版本 21H2 以上

步驟 1：更新 NVIDIA 驅動程式（Windows 端）

前往 NVIDIA 驅動程式下載頁面
選擇你的顯示卡型號
下載並安裝最新驅動程式

重要：在 WSL2 中，你不需要在 Linux 內安裝 NVIDIA 驅動程式。WSL2 會自動使用 Windows 端的驅動程式。

步驟 2：在 WSL2 中安裝 CUDA Toolkit

開啟 Ubuntu 終端機，依序執行：

# 移除舊的 GPG key（如果有的話）
sudo apt-key del 7fa2af80

# 下載並安裝 CUDA keyring
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb

# 更新套件清單
sudo apt update

# 安裝 CUDA Toolkit（選擇你需要的版本）
sudo apt install -y cuda-toolkit-12-4

步驟 3：設定環境變數

將 CUDA 路徑加入環境變數：

# 編輯 .bashrc
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc

# 重新載入設定
source ~/.bashrc

步驟 4：驗證 CUDA 安裝

# 檢查 NVIDIA GPU 狀態
nvidia-smi

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

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 545.23.06    Driver Version: 546.33       CUDA Version: 12.3     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce ...  On   | 00000000:01:00.0  On |                  N/A |
| 30%   45C    P8    15W / 170W |    512MiB /  8192MiB |      2%      Default |
+-------------------------------+----------------------+----------------------+

步驟 5：安裝 PyTorch（GPU 版本）

# 安裝 pip（如果尚未安裝）
sudo apt install -y python3-pip

# 安裝 PyTorch GPU 版本
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

驗證 PyTorch 是否能存取 GPU：

python3 -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'GPU: {torch.cuda.get_device_name(0)}')"

預期輸出：

CUDA available: True
GPU: NVIDIA GeForce RTX 3080

第四部分：VS Code Remote WSL 整合

Visual Studio Code 是目前最受歡迎的程式碼編輯器之一。透過 Remote WSL 擴充功能，你可以在 Windows 端使用 VS Code，同時在 WSL2 Linux 環境中執行程式碼。

步驟 1：安裝 VS Code（Windows 端）

如果尚未安裝 VS Code：

官方下載連結：https://code.visualstudio.com/

步驟 2：安裝 WSL 擴充功能

開啟 VS Code
按下 Ctrl + Shift + X 開啟擴充功能面板
搜尋「WSL」
安裝 Microsoft 官方的「WSL」擴充功能

擴充功能 ID：ms-vscode-remote.remote-wsl，由 Microsoft 官方發布。安裝後會在左下角狀態列新增 Remote 連接按鈕。

步驟 3：在 WSL 中開啟 VS Code

方法一：從 WSL 終端機啟動

# 在目前目錄開啟 VS Code
code .

首次執行時，VS Code 會自動在 WSL 中安裝所需的伺服器元件。

方法二：從 VS Code 連接

按下 F1 開啟命令面板
輸入「WSL: Connect to WSL」
選擇你的 Ubuntu 發行版

步驟 4：安裝 Python 擴充功能（在 WSL 中）

連接到 WSL 後，VS Code 左下角會顯示「WSL: Ubuntu」。此時安裝的擴充功能會安裝在 WSL 環境中：

按下 Ctrl + Shift + X
搜尋並安裝「Python」擴充功能
搜尋並安裝「Jupyter」擴充功能

連接成功指標：VS Code 視窗左下角會顯示綠色圖示與「WSL: Ubuntu」字樣，表示已成功連接到 WSL 環境。此時在 VS Code 中開啟的終端機會直接是 Linux shell。

擴充功能	用途
Python	Python 語言支援
Jupyter	Notebook 支援
Pylance	進階 Python IntelliSense
GitHub Copilot	AI 程式碼補全
Docker	Docker 檔案支援

實用技巧與效能優化

1. 檔案系統效能優化

黃金法則：將專案檔案存放在 Linux 檔案系統中，而非 Windows 磁碟。

# 慢：存取 Windows 檔案（跨檔案系統）
cd /mnt/c/Users/yourname/projects

# 快：存取 Linux 原生檔案
cd ~/projects

效能差異可達 5-10 倍！

2. 記憶體限制設定

WSL2 預設會使用大量記憶體。你可以透過設定檔限制：

在 Windows 中建立 %UserProfile%\.wslconfig 檔案：

[wsl2]
memory=8GB       # 限制最大記憶體為 8GB
processors=4     # 限制使用 4 個 CPU 核心
swap=2GB         # 設定 swap 大小

修改後需重新啟動 WSL：

wsl --shutdown

3. 常用 WSL 指令

# 列出已安裝的發行版
wsl --list --verbose

# 設定預設發行版
wsl --set-default Ubuntu

# 關閉所有 WSL 實例
wsl --shutdown

# 匯出發行版為備份
wsl --export Ubuntu ubuntu-backup.tar

# 匯入發行版
wsl --import Ubuntu-New C:\WSL\Ubuntu-New ubuntu-backup.tar

4. 在 Windows 檔案總管中存取 WSL 檔案

在檔案總管網址列輸入：

\\wsl$\Ubuntu\home\yourname

或從 WSL 終端機開啟檔案總管：

explorer.exe .

常見問題排解

Q1: 安裝時出現「虛擬機器平台」錯誤

錯誤訊息：Please enable the Virtual Machine Platform Windows feature

解決方案：

以系統管理員身分開啟 PowerShell
執行以下指令：

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

重新啟動電腦

Q2: WSL2 無法連接網路

解決方案：重置網路設定

# 以系統管理員身分在 PowerShell 執行
netsh winsock reset
netsh int ip reset

重新啟動電腦後應可解決。

Q3: Docker 顯示「Cannot connect to the Docker daemon」

解決方案：

確認 Docker Desktop 正在運行
在 Docker Desktop 設定中確認 WSL 整合已啟用
重新啟動 Docker Desktop

# 在 WSL 中確認 Docker 狀態
docker info

Q4: nvidia-smi 顯示「command not found」

可能原因：

Windows 端 NVIDIA 驅動程式版本過舊
WSL2 核心需要更新

解決方案：

# 更新 WSL 核心
wsl --update

# 重新啟動 WSL
wsl --shutdown

Q5: VS Code Remote WSL 連接緩慢

解決方案：

確保 VS Code 已更新到最新版本
在 WSL 中清除 VS Code Server 快取：

rm -rf ~/.vscode-server

重新連接

總結與下一步

恭喜你完成了完整的 WSL2 開發環境設定！你現在擁有：

完整的 Linux 環境：Ubuntu 運行在 WSL2 上
容器化開發：Docker Desktop 整合
GPU 加速：CUDA 支援 AI 訓練
專業編輯器：VS Code Remote WSL 整合

學習路線建議

階段	建議學習	相關資源
基礎	Linux 指令、Git 操作	Linux 命令列入門
進階	Docker 容器化、Python 虛擬環境	Docker 官方教學
AI 開發	PyTorch、Hugging Face	PyTorch 官方教學

下一步行動

練習 Linux 基礎指令：ls、cd、mkdir、rm 等
建立第一個 Python 專案：在 ~/projects 目錄下開始
嘗試運行 AI 模型：使用 Ollama 或 Hugging Face

相關文章：

參考資源：

Windows 11 WSL2 完整安裝指南：AI 開發者的 Linux 環境建置

目錄

為什麼 AI 開發者需要 WSL2？

前置條件確認

系統需求

如何檢查 Windows 版本

如何確認硬體虛擬化已啟用

第一部分：WSL2 基礎安裝

步驟 1：以系統管理員身分開啟終端機

步驟 2：執行 WSL 安裝指令

步驟 3：重新啟動電腦

步驟 4：完成 Ubuntu 初始設定

步驟 5：驗證安裝成功

步驟 6：更新系統套件

第二部分：Docker Desktop 整合

為什麼要用 Docker + WSL2？

步驟 1：下載 Docker Desktop

步驟 2：安裝 Docker Desktop

步驟 3：設定 WSL 整合

步驟 4：驗證 Docker 運作

實用範例：運行 Jupyter Lab

第三部分：GPU 與 CUDA 設定

系統需求

步驟 1：更新 NVIDIA 驅動程式（Windows 端）

步驟 2：在 WSL2 中安裝 CUDA Toolkit

步驟 3：設定環境變數

步驟 4：驗證 CUDA 安裝

步驟 5：安裝 PyTorch（GPU 版本）

第四部分：VS Code Remote WSL 整合

步驟 1：安裝 VS Code（Windows 端）

步驟 2：安裝 WSL 擴充功能

步驟 3：在 WSL 中開啟 VS Code

步驟 4：安裝 Python 擴充功能（在 WSL 中）

推薦的 AI 開發擴充功能

實用技巧與效能優化

1. 檔案系統效能優化

2. 記憶體限制設定

3. 常用 WSL 指令

4. 在 Windows 檔案總管中存取 WSL 檔案

常見問題排解

Q1: 安裝時出現「虛擬機器平台」錯誤

Q2: WSL2 無法連接網路

Q3: Docker 顯示「Cannot connect to the Docker daemon」

Q4: nvidia-smi 顯示「command not found」

Q5: VS Code Remote WSL 連接緩慢

總結與下一步

學習路線建議

下一步行動