Windows 11 WSL2 完整安裝：5 分鐘閃電上手

這不是一般的教學文章

✅ 互動檢查清單：勾選進度，可匯出到你的筆記工具 ✅ 決策樹導航：根據你的情況，只看需要的內容 ✅ Prompt 工具包：帶走可重複使用的 AI 對話模板 ✅ 踩坑實錄：真實經驗，AI 搜不到的避雷指南

選擇你的學習路徑

前置條件確認

30 秒快速檢查

0/3 完成

Windows 版本：Windows 11 或 Windows 10 2004+（按 Win+R 輸入 winver 檢查）

系統類型：64 位元

虛擬化已啟用：工作管理員 → 效能 → CPU → 右下角顯示「虛擬化：已啟用」

如何檢查虛擬化狀態

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

如果顯示「已停用」，需進入 BIOS 啟用：

Intel CPU：啟用 Intel VT-x
AMD CPU：啟用 AMD-V

第一部分：WSL2 基礎安裝

WSL2 安裝步驟

0/9 完成

以系統管理員身分開啟終端機（Win → 搜尋「終端機」→ 右鍵 → 以系統管理員身分執行）

執行 wsl --install

看到「已成功安裝」訊息

儲存所有工作，重新啟動電腦

Ubuntu 視窗自動開啟

輸入 Linux 使用者名稱（小寫字母）

設定密碼（輸入時不顯示字元是正常的）

執行 cat /etc/os-release 確認 Ubuntu 版本

執行 sudo apt update && sudo apt upgrade -y 更新系統

WSL2 vs WSL1 一句話記住

WSL2 = 完整 Linux 核心，WSL1 = 翻譯層

比較	WSL1	WSL2
架構	翻譯層	輕量 VM + 完整核心
Docker	❌ 不支援	✅ 原生支援
GPU	❌ 不支援	✅ CUDA 支援
檔案效能（Linux 內）	較慢	快

症狀：執行 wsl --install 成功，但重開機後沒有 Ubuntu 視窗

原因：某些情況下預設發行版沒有自動安裝

解法：

# 手動安裝 Ubuntu
wsl --install -d Ubuntu

我怎麼發現的：第一次在公司新電腦裝，等了 10 分鐘才發現要手動裝 😅

第二部分：Docker Desktop 整合

Docker 安裝步驟

0/11 完成

前往 docker.com/products/docker-desktop 下載

執行安裝程式

重要：勾選「Use WSL 2 instead of Hyper-V」

完成安裝，重新開機

開啟 Docker Desktop

Settings → Resources → WSL Integration

啟用「Enable integration with my default WSL distro」

啟用你的 Ubuntu 發行版

Apply & Restart

在 Ubuntu 終端機執行 docker --version 確認

執行 docker run hello-world 看到成功訊息

為什麼用 Docker

Docker = 「在我電腦上可以跑」的終極解法

沒有 Docker	有 Docker
Python 3.8 和 3.11 打架	每個專案獨立環境
「你少裝了 XXX」	一個指令全部搞定
部署要重新設定	開發環境 = 生產環境

快速體驗：

docker run -p 8888:8888 jupyter/pytorch-notebook

症狀：開著 Docker Desktop，電腦越來越慢，記憶體被吃光

原因：WSL2 VM 預設會動態擴展記憶體，最高可用到系統 80%

解法：建立 .wslconfig 限制記憶體

在 Windows 的 %UserProfile% 目錄建立 .wslconfig：

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

然後重啟 WSL：

wsl --shutdown

血淚教訓：在 16GB 筆電上開 Docker 跑模型訓練，差點當機 💀

第三部分：GPU 與 CUDA 設定

GPU 設定步驟

0/8 完成

確認有 NVIDIA 顯示卡（GTX 1060 以上，建議 RTX 系列）

確認 Windows 11 或 Windows 10 21H2+

前往 nvidia.com/Download 下載最新驅動並安裝

重新開機

在 WSL2 執行 CUDA 安裝指令（見下方）

設定環境變數

執行 nvidia-smi 看到 GPU 資訊

安裝 PyTorch GPU 版並驗證

CUDA 安裝指令（在 WSL2 Ubuntu 中執行）：

# 下載並安裝 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
sudo apt install -y cuda-toolkit-12-4

# 設定環境變數
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

安裝 PyTorch GPU 版：

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

驗證：

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

WSL2 GPU 原理

WSL2 不需要在 Linux 內裝 NVIDIA 驅動

Windows 驅動會自動橋接到 WSL2：

Windows NVIDIA Driver
        ↓ (自動橋接)
    WSL2 Linux
        ↓
   CUDA Toolkit
        ↓
 PyTorch / TensorFlow

重點：

✅ 在 Windows 安裝最新 NVIDIA 驅動
❌ 不要在 WSL2 內安裝 nvidia-driver
✅ 只需在 WSL2 內安裝 CUDA Toolkit

症狀：nvidia-smi 正常顯示 GPU，但 torch.cuda.is_available() 回傳 False

原因：PyTorch 安裝了 CPU 版本，或 CUDA 版本不匹配

解法：

# 先移除舊的 PyTorch
pip uninstall torch torchvision torchaudio

# 安裝正確的 CUDA 版本
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

確認版本對應：nvidia-smi 右上角的 CUDA Version 要和 PyTorch 的 cu 版本匹配。

第四部分：VS Code Remote WSL 整合

VS Code 整合步驟

0/6 完成

前往 code.visualstudio.com 下載安裝 VS Code

開啟 VS Code，按 Ctrl+Shift+X 開啟擴充功能

搜尋「WSL」，安裝 Microsoft 官方的擴充功能

在 Ubuntu 終端機執行 code .

確認左下角顯示「WSL: Ubuntu」

安裝 Python 擴充功能（在 WSL 端）

VS Code Remote 架構

VS Code 跑在 Windows，程式碼跑在 Linux

┌─────────────────┐     ┌─────────────────┐
│   Windows 端    │     │    WSL2 端      │
│  ┌───────────┐  │     │  ┌───────────┐  │
│  │  VS Code  │◄─┼─────┼─►│ VS Code   │  │
│  │    UI     │  │     │  │  Server   │  │
│  └───────────┘  │     │  └───────────┘  │
└─────────────────┘     └─────────────────┘

優點：Windows 的 UI 體驗 + Linux 的開發環境

症狀：開啟專案要等 30 秒以上，常常卡住

原因：專案放在 /mnt/c（Windows 磁碟），跨檔案系統效能差

解法：

# 把專案移到 Linux 檔案系統
mkdir -p ~/projects
mv /mnt/c/Users/你的名字/project ~/projects/

# 以後都在 Linux 檔案系統工作
cd ~/projects
code .

效能差異：/mnt/c 效能只有 Linux 原生的 10-20%！

實用技巧與效能優化

效能三條黃金法則

三條黃金法則

專案放 ~/ 不放 /mnt/c — 效能差 5-10 倍
限制 WSL2 記憶體 — 避免吃光系統資源
用 VS Code Remote — 不要在 Windows 跑 Linux 檔案

症狀：npm install 花了 15 分鐘，平常只要 30 秒

原因：專案放在 /mnt/c，每個檔案操作都要跨檔案系統

解法：

cd ~
git clone <你的專案>
cd <專案名>
npm install  # 現在應該 30 秒內完成

數據對比：

/mnt/c npm install：15 分鐘
~/ npm install：30 秒
差距：30 倍

常見問題排解

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 無法連接網路

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

然後重新開機。

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

確認 Docker Desktop 正在執行
Settings → Resources → WSL Integration 已啟用
嘗試重啟 Docker Desktop

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

wsl --update
wsl --shutdown

然後重新開啟 Ubuntu。

Q5: VS Code Remote WSL 連接緩慢

rm -rf ~/.vscode-server

然後重新連接。

總結與下一步

完成確認

0/6 完成

WSL2 + Ubuntu 已安裝並可正常使用

Docker Desktop 已整合 WSL2（如需要）

nvidia-smi 和 PyTorch GPU 可正常運作（如需要）

VS Code Remote WSL 可正常連接

專案已放在 Linux 檔案系統（~/）

.wslconfig 已設定記憶體限制

相關文章：

參考資源：

【互動式教學】Windows 11 WSL2 完整安裝：5 分鐘閃電上手

Windows 11 WSL2 完整安裝：5 分鐘閃電上手

選擇你的學習路徑

選擇你的學習路徑

前置條件確認

30 秒快速檢查

如何檢查虛擬化狀態

第一部分：WSL2 基礎安裝

WSL2 安裝步驟

WSL2 vs WSL1 一句話記住

安裝完找不到 Ubuntu

深入理解 WSL2

第二部分：Docker Desktop 整合

Docker 安裝步驟

為什麼用 Docker

Docker Desktop 吃掉所有記憶體

Docker 實戰問題

第三部分：GPU 與 CUDA 設定

GPU 設定步驟

WSL2 GPU 原理

nvidia-smi 正常但 PyTorch 抓不到 GPU

GPU 問題診斷

第四部分：VS Code Remote WSL 整合

VS Code 整合步驟

VS Code Remote 架構

VS Code 開啟 WSL 專案超慢

實用技巧與效能優化

效能三條黃金法則

npm install 慢到懷疑人生

常見問題排解

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

Q2: WSL2 無法連接網路

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

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

Q5: VS Code Remote WSL 連接緩慢

總結與下一步

完成確認

打造你的學習計畫