WSL 2 安裝指南（Windows 11）

在 Windows 11 全新重灌系統上安裝 WSL 2 + Ubuntu，並將虛擬磁碟指定至非系統碟（D 槽）的完整 SOP，含啟動目錄修正與建議設定。

概述

WSL 2（Windows Subsystem for Linux 2）使用完整 Linux 核心（輕量 Hyper-V VM），相較 WSL 1 的系統呼叫轉譯層有根本差異：檔案系統效能接近原生、支援 Docker、支援 GUI（WSLg）。Windows 11 透過 wsl --install 安裝的發行版預設即為 WSL 2。

將虛擬磁碟放在 D 槽的動機：避免 C 槽（系統碟）被大型 Linux 環境佔滿，同時在重灌 Windows 時保留 Linux 環境。

核心內容

WSL 1 vs WSL 2 比較

比較項目	WSL 1	WSL 2
架構	系統呼叫轉譯層	完整 Linux 核心（輕量 VM）
系統呼叫相容性	部分支援	完整支援
檔案系統效能（Linux 內）	較慢	接近原生
Docker 支援	不支援	原生支援
GUI 應用（WSLg）	不支援	支援

安裝管道比較

比較項目	wsl --install（命令列）	Microsoft Store 手動安裝
自動啟用 WSL 平台元件	✅	❌ 需自行確認
支援 --location 指定路徑	✅	❌ 預設裝在 C 槽
操作步驟	一條指令	需分步操作

建議：全新重灌一律使用命令列方式。

啟動目錄問題

安裝後常見問題：進入 WSL 時工作目錄顯示 /mnt/c/Users/<WindowsUser> 而非 /home/<username>。

根本原因：WSL 預設將 Windows PATH 附加到 Linux PATH（appendWindowsPath = true），導致啟動時沿用 Windows 傳入的工作目錄。

不同進入方式有不同解法：

進入方式	推薦解法
Windows Terminal 的 Ubuntu Profile	在 wsl.conf 設定 appendWindowsPath = false（方法 A，推薦）
PowerShell 內執行 wsl	使用 wsl ~ 進入

方法 A 的副作用：設定後在 WSL 內無法直接呼叫 explorer.exe、code 等 Windows 指令，需用完整路徑或在 ~/.bashrc 手動加回。

nano ~/.bashrc
alias explorer="/mnt/c/Windows/explorer.exe"
source ~/.bashrc

關鍵要點

• 開發專案檔案應放在 Linux 檔案系統（~/projects/），不要放在 /mnt/c/ 或 /mnt/d/，跨 WSL/Windows 邊界的 I/O 速度明顯較慢
• WSL 2 使用 Hyper-V 後端，若系統有舊版 VirtualBox 或 VMware 可能衝突
• --location 參數需要 WSL 引擎為最新版（先執行 wsl --update）
• 不建議在 .bashrc 無條件加 cd ~，會影響 scp、rsync 等非互動式工具的行為

實際應用

安裝完成後，常見的開發環境擴展：

• VS Code：安裝 WSL 延伸模組，即可在 VS Code 中直接編輯 Linux 檔案系統內的專案
• Docker Desktop：啟用「Use the WSL 2 based engine」，在 WSL 內原生使用 Docker
• uv / Python：直接在 Ubuntu 內安裝 uv，管理 Python 版本（詳見uv Python 版本與環境管理）

部署設定參考

安裝 SOP（D 槽）

# Step 1：更新 WSL 引擎（以系統管理員執行）
wsl --update

# Step 2：建立目標資料夾
mkdir D:\WSL\Ubuntu

# Step 3：安裝至 D 槽
wsl --install -d Ubuntu --location D:\WSL\Ubuntu

# Step 4：重新啟動電腦

# Step 5：首次啟動 Ubuntu → 建立 UNIX 使用者名稱與密碼

# Step 6：更新系統套件（Ubuntu 內）
sudo apt update && sudo apt -y upgrade

# Step 7：驗證
wsl -l -v          # STATE: Running/Stopped, VERSION: 2
dir D:\WSL\Ubuntu  # 確認 ext4.vhdx 存在

備用方案：Export / Import 搬移法

若 --location 不可用，或已裝在 C 槽需搬移：

# 關閉 WSL
wsl --shutdown

# 匯出
wsl --export Ubuntu D:\WSL\ubuntu-backup.tar

# 取消註冊（⚠️ 刪除 C 槽虛擬磁碟，確認匯出完成再執行）
wsl --unregister Ubuntu

# 匯入至 D 槽
wsl --import Ubuntu D:\WSL\Ubuntu D:\WSL\ubuntu-backup.tar --version 2

# 修正預設使用者（匯入後預設為 root）
# 在 Ubuntu 內執行：
sudo nano /etc/wsl.conf
# 加入 [user] default=<your_username>

# 重啟 WSL
wsl --shutdown

# 清理備份
del D:\WSL\ubuntu-backup.tar

建議的 wsl.conf 完整配置

sudo tee /etc/wsl.conf << 'EOF'
[user]
default=<your_username>

[automount]
options = "metadata"

[interop]
appendWindowsPath = false

[boot]
systemd = true
EOF

# 套用設定
wsl --shutdown

區段	設定	用途
[user]	default=<username>	指定預設登入使用者（Import 後必填）
[automount]	options = "metadata"	在 /mnt/c 等 Windows 掛載磁碟上啟用 chmod/chown
[interop]	appendWindowsPath = false	不將 Windows PATH 帶入 Linux；修正 Terminal 啟動目錄問題
[boot]	systemd = true	啟用 systemd，支援 systemctl 管理服務

資源限制（.wslconfig）

在 %USERPROFILE%\.wslconfig 建立（Windows 使用者目錄下）：

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

# 套用
wsl --shutdown

啟動目錄修正

方法 A（推薦）：在 wsl.conf 設定 appendWindowsPath = false（見上方完整配置）

方法 B：修改 Terminal Profile 啟動目錄（settings.json）：

"startingDirectory": "//wsl$/Ubuntu/home/<your_username>"

方法 C：修改 Terminal Profile 的 commandline：

"commandline": "wsl.exe -d Ubuntu --cd ~"

PowerShell 進入 WSL 時：

wsl ~          # 直接進入家目錄

# 或設定別名
# 在 PowerShell Profile（notepad $PROFILE）加入：
function Enter-WSL { wsl ~ }
Set-Alias -Name wsl2 -Value Enter-WSL

安裝後常用工具

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

常用指令速查

wsl -l -v                                          # 查看發行版與版本
wsl --list --online                                # 查看可安裝的發行版
wsl --shutdown                                     # 關閉所有 WSL 執行個體
wsl --update                                       # 更新 WSL 引擎
wsl --set-default <DistroName>                     # 設定預設發行版
wsl --export <DistroName> <FilePath.tar>           # 匯出
wsl --import <DistroName> <InstallPath> <File.tar> --version 2  # 匯入
wsl --unregister <DistroName>                      # 取消註冊（刪除）
wsl                                                # 進入預設發行版
wsl -d <DistroName>                                # 進入指定發行版
wsl ~                                              # 進入預設發行版並切到家目錄

常見問題排除

問題	解決方式
安裝卡在 0%	改用 wsl --install --web-download -d Ubuntu
錯誤碼 14107	手動開啟「設定 → 選用功能 → 更多 Windows 功能」勾選「Virtual Machine Platform」
虛擬化未啟用	進入 BIOS/UEFI 開啟 Intel VT-x 或 AMD-V
--location 無法辨識	先執行 wsl --update
Import 後預設使用者為 root	/etc/wsl.conf 設定 [user] default=<username>
WSL 佔用記憶體過大	.wslconfig 限制 memory 上限
Terminal 啟動時工作目錄在 /mnt/c/	wsl.conf 設定 appendWindowsPath = false
PowerShell wsl 後工作目錄不在家目錄	改用 wsl ~
appendWindowsPath=false 後無法呼叫 Windows 指令	用完整路徑呼叫，或在 ~/.bashrc 手動加回需要路徑

相關概念

• uv Python 版本與環境管理 — WSL Ubuntu 內的 Python 環境管理方案
• WSL2 Terminal 美化與功能強化 — 在 WSL2 Ubuntu 上以 Zsh 與 Powerlevel10k 建立高效率終端環境
• PowerShell Terminal 美化指南 — Windows 端終端環境美化，與 WSL2 可形成一致操作體驗
• Volta Node.js 版本管理 — 在 Windows/WSL 開發流程中管理 Node.js 版本與專案 pin
• PowerShell HTTPS Proxy 設定 — 企業環境中 WSL 與 Windows 雙端的 Proxy 設定對照
• WSL 環境設定進階技巧 — PATH 汙染過濾與 DNS 解析失敗修復

來源

• 原始素材：Windows 11 WSL 完整安裝指南