啟用與設定 WSL

在使用 WSL Dashboard 之前，您的 Windows 系統必須正確啟用並設定好 WSL 2 環境。本文分為以下三大部分：

1. 啟用與設定 WSL：完成 WSL 2 的基礎安裝與設定。
2. 命令可用不等於安裝成功：說明 wsl 命令可執行並不代表可以成功安裝 Linux。
3. 安裝失敗排查：設定完成後安裝仍失敗時的檢查與修復方法。

1. 啟用與設定 WSL

本章節將引導您完成必要的基本設定。完成本章後，請閱讀 第 2 章 了解命令可用與安裝成功之間的區別；若安裝仍出現問題，請參考 第 3 章。

1.1 檢查系統需求

WSL 2 對 Windows 版本有最低要求。請按下 Win + R，輸入 winver 檢查您的版本：

• Windows 10: 版本 1903 或更高，且內部版本 (Build) 需為 18362 或更高。
• Windows 11: 所有版本均支援。

IMPORTANT

如果您的版本過低，請先透過「Windows 更新」升級您的系統。

1.2 開啟硬體虛擬化

WSL 2 基於虛擬化技術執行，因此必須在主機板 BIOS/UEFI 中啟用 虛擬化技術 (Virtualization Technology)。

• 檢查方法: 開啟「工作管理員」→「效能」標籤頁 →「CPU」。
• 查看狀態: 確認右下角的「虛擬化」狀態顯示為 「已啟用」。
• 開啟方式: 若未啟用，您需要重新啟動電腦進入 BIOS/UEFI 設定，找到類似 Intel VT-x 或 AMD-V 的選項並將其設為 Enabled。

1.3 啟用 Windows 相關功能

您需要開啟 Windows 的「適用於 Linux 的 Windows 子系統」和「虛擬機平台」功能。

方法 A：透過圖形介面（推薦）

1. 按下 Win + S，搜尋並開啟 「啟用或關閉 Windows 功能」。
2. 勾選以下兩項：
   • 適用於 Linux 的 Windows 子系統 (Windows Subsystem for Linux)
   • 虛擬機平台 (Virtual Machine Platform)
3. 點擊「確定」，並在提示時重新啟動電腦。

方法 B：透過命令列（管理員權限）

以管理員身份執行 PowerShell 並執行以下命令：

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

# 啟用虛擬機平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

執行完畢後，請手動重新啟動電腦。

1.4 安裝/更新 WSL 核心

現代版本的 Windows 可以透過 Microsoft Store 取得 WSL 更新。

• 下載位址: Microsoft Store - Windows Subsystem for Linux
• 手動下載: 如果無法使用商店，可以從 WSL GitHub Releases 下載最新的 .msixbundle 或 .msi 安裝包進行離線安裝。

1.5 設定 WSL 2 為預設版本

為了確保新安裝的發行版本預設使用 WSL 2，請在終端機執行：

wsl --set-default-version 2

1.6 常見問題

• 錯誤 0x80370102: 通常是因為 BIOS 中未開啟虛擬化，或者 Hyper-V 存在衝突。
• WSL 1 與 WSL 2 切換: 您可以使用 wsl --set-version <發行版本名稱> 2 將現有的 WSL 1 執行個體升級到 WSL 2。

2. 命令可用不等於安裝成功

wsl --version、wsl -l -v 等命令能夠正常執行，並不意味著已經具備安裝 Linux 的條件。兩者處於不同階段，不能畫上等號。

命令可用，只說明：

• ✅ Windows 中 WSL 元件已經啟用/安裝好了
• ✅ wsl.exe 命令列工具是可用的
• ✅ 系統能辨識 WSL 相關命令

但成功安裝 Linux 發行版本，還需要滿足額外條件。 常見會卡住的地方有：

1. 虛擬化被關閉：BIOS/UEFI 中未開啟 VT-x / AMD-V，WSL 2 無法啟動，或安裝發行版本時報告虛擬化錯誤（檢查方法見 1.2 開啟硬體虛擬化）。
2. Windows 版本/內部版本過低：WSL 2 對核心和版本有要求，家用版、過舊的企業映像可能功能不全（檢查方法見 1.1 檢查系統需求）。
3. 尚未實際安裝 Linux 發行版本：wsl -l -v 僅列出已安裝的發行版本，什麼都沒裝時清單就是空的，不代表可以直接執行 Ubuntu。
4. 網路 / Microsoft Store 問題：wsl --install -d <發行版本> 需要從商店或網路擷取映像，公司網路、代理、防火牆都可能阻斷。
5. 權限不足：安裝發行版本或修改 WSL 設定需要管理員權限。

TIP

簡單來說：WSL 命令能用 ≠ Linux 已就緒，只是拿到了「入場券」，還沒有真正安裝系統。

3. 安裝失敗排查

按照 第 1 章 完成設定（或您認為自己已完成設定）後，若執行 wsl --install 仍然失敗，請依以下順序檢查。

3.1 先做「一鍵檢測」

以管理員身份執行 PowerShell，依序執行：

wsl --install --no-distribution
wsl --set-default-version 2

• ✅ 如果這兩條命令都能順利執行，說明 WSL 選用元件已啟用，虛擬化條件基本滿足。
• ❌ 如果失敗，會直接提示缺少什麼（如虛擬機平台、Hyper-V、BIOS 虛擬化等）。

再執行 systeminfo，在輸出中確認出現 Virtualization Enabled In Firmware: Yes。若以上均無報錯，基本上可以放心執行 wsl --install 安裝發行版本。

NOTE

沒有任何命令能 100% 保證 wsl --install 一定成功，但上述檢測可以確認安裝條件是否已滿足。

3.2 手動檢測清單

如果「一鍵檢測」仍無法定位問題，可逐項檢查：

1. 檢測 BIOS/韌體虛擬化是否開啟：管理員 PowerShell 執行 systeminfo，輸出中必須看到 Virtualization Enabled In Firmware: Yes。
2. 檢測 Windows 功能是否已開啟：

   Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
   Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

   兩條命令的狀態均應為 Enabled。
3. 檢測 WSL 是否可用：執行 wsl --version 應有正常輸出；若提示命令不存在，說明 WSL 元件未安裝，請回到 第 1 章。
4. 檢測能否使用 WSL 2（核心 & 虛擬機平台）：執行 wsl --set-default-version 2 應成功返回。常見失敗原因：未啟用虛擬機平台，或 BIOS 中未開啟 VT-x / AMD-V。

3.3 常見失敗原因速查

情況	說明	處理方式
BIOS 未開啟虛擬化	必定失敗	重新啟動進入 BIOS 開啟 VT-x / AMD-V（見 1.2）
Windows 10 低於 19041	不支援 wsl --install	升級系統（見 1.1）
企業環境停用 Hyper-V / 虛擬化	可能失敗	聯絡系統管理員
舊版家用版系統	需手動安裝	按 1.4 手動安裝 WSL 核心

3.4 錯誤 0xc03a0014：找不到虛擬磁碟支援提供者

錯誤訊息為 Cannot find a virtual disk support provider for the specified file。這不是 Linux 發行版本本身的問題，而是 Windows 的 VHD/VHDX 虛擬磁碟堆疊沒有正常運作，WSL 2 在註冊發行版本、建立/掛載 ext4.vhdx 時失敗。

先做最小驗證：以管理員身份執行 PowerShell，執行 New-VHD 測試（例如 New-VHD -Path C:\test.vhdx -SizeBytes 1GB）。如果這條命令也回報同樣的錯誤，問題 100% 在 Windows 端，與發行版本無關。

依以下順序排查修復：

1. Virtual Disk 服務未執行：開啟 services.msc，找到 Virtual Disk 服務，將啟動類型設為「自動」並啟動它。

2. WSL / 虛擬機平台功能未啟用（或未生效）：重新執行 1.3 啟用 Windows 相關功能 中的命令，然後必須重新啟動。Windows 家用版沒有完整的 Hyper-V，但 WSL 2 只需要虛擬機平台，並非 Hyper-V 管理介面。

3. 虛擬磁碟驅動程式/裝置缺失：開啟裝置管理員，檢查「系統裝置 / 儲存控制器」中是否存在：

   • Microsoft Virtual Disk Provider
   • Microsoft Virtual Drive Enumerator
   • Microsoft VHD Loopback Controller

   缺少時可透過 hdwwiz.exe 手動新增（儲存控制器 → Microsoft → Microsoft VHD 回送控制器），並確認 FsDepends 服務未被停用。

4. 匯入的映像不符合 WSL 要求：使用 wsl --import --vhd 時，VHDX 必須是 ext4 檔案系統，不能是 LUKS 加密磁碟、普通 raw.img、Live ISO 或 NTFS/FAT 格式化後的空磁碟。.img / .qcow2 / .iso 不能直接 wsl --import --vhd。

5. 路徑/權限/檔案系統問題：目標目錄必須在 NTFS 磁碟上（FAT32/exFAT 不行）；路徑避免中文、空格和特殊符號；不要從網路磁碟、OneDrive、壓縮資料夾匯入；務必使用真正的管理員 PowerShell（而非一般終端機）。

6. 系統元件損壞：依序執行 DISM 與 SFC 修復系統元件，然後重新嘗試：

   DISM.exe /Online /Cleanup-Image /RestoreHealth
   sfc /scannow

TIP

第三方虛擬機（VirtualBox、VMware）或安全軟體的沙箱/加固功能（如 360、火絨）可能干擾虛擬磁碟操作，排查時可以暫時關閉再試。