Windows 裝 Docker Desktop 先搞定 WSL

以前我以為裝 Docker Desktop 是點下一步，現在我只把它當成 WSL 先備妥、再安裝、重開機、最後驗證的流程。

我在 Windows 上裝 Docker Desktop 已經踩過夠多次坑了。最煩的不是安裝檔本身，而是它看起來很單純，實際上卻把一堆前置條件藏在別的頁面裡：WSL、虛擬化、Windows 功能、還有那個你以為可以先跳過、結果後面一定回來討債的重開機。你一邊點安裝，一邊以為自己在做一件很小的事，結果半小時後開始懷疑是 Docker 壞了，或是 Windows 壞了，或是人生壞了。

我後來是看了 Docker Docs 的 Windows 安裝頁，才把這件事拆清楚。它其實已經把方向講出來了，只是寫法還是很像產品文件：資訊都在，但順序不夠直白。我想要的不是一堆導覽和補充說明，我要的是一份照著做就能過的清單。

所以這篇我直接把流程翻成實戰版。先把 WSL 弄好，再裝 Docker Desktop，該重開就重開，最後用真的容器去驗證。這樣做的好處很簡單：你不會把時間浪費在猜到底是 Docker、WSL，還是 Windows 自己在鬧脾氣。

Docker Desktop 只是表面，WSL 才是底層

Run either the install or update command. You may be prompted to restart your machine. For more information, refer to Install WSL. Go to the official WSL GitHub Releases page.

這段話的意思很直接：Docker Desktop 在 Windows 上不是獨立世界，它是踩在 WSL 2 這條路上跑的。WSL 沒裝好、版本太舊、或是更新沒吃進去，Docker 看起來可能還能開，但之後跑容器就會開始卡。官方把你導去 Microsoft 的 WSL 安裝頁，還有 WSL GitHub Releases，就是在告訴你底層狀態比 UI 重要。

我自己最常遇到的，就是新機器剛裝好 Docker Desktop，視窗能開、托盤圖示也正常，結果一跑容器就慢得像在等遠端主機回應。那種狀況最煩，因為它不會直接報一個很誇張的錯，它只會讓你一直懷疑是不是自己哪裡操作錯了。其實很多時候只是 WSL 還沒準備好。

實操寫法很簡單：先確認 WSL 是否已安裝，而且是 WSL 2。你如果不確定，就先當成沒有。先裝或更新 WSL，再照 Windows 的提示重開機。團隊如果有標準開發機流程，這一步應該放在 Docker 之前，不要期待 Docker 安裝程式會順手幫你補齊整個系統狀態。

• 先檢查 WSL 是否存在，版本是不是 2。
• 如果機器很久沒整理，先更新 WSL 再裝 Docker。
• 任何 WSL 變更後都重開，不要賭運氣。

安裝檔很簡單，主機狀態才是麻煩來源

Docker 的安裝頁看起來像一個很乾淨的下載按鈕，這種簡潔很容易騙人。真正的依賴其實在 Windows 主機狀態：虛擬化有沒有開、Windows 功能有沒有啟用、公司政策有沒有鎖住、BIOS 裡的設定有沒有過。這些東西不先處理，Docker Desktop 再乾淨也只是表面乾淨。

我看過不少開發者把問題怪到 Docker 身上，結果最後發現是 Hyper-V 沒開、虛擬化沒開、或是 WSL kernel 太舊。這種 bug 很浪費時間，因為你會先在應用層面亂查，最後才發現地基根本沒打好。這也是我現在看 Windows 上的 Docker 安裝流程時，第一個先看底層條件的原因。

實操寫法：在你開始裝之前，先確認這台 Windows 能不能真的跑 Linux containers。把 Windows 版本相容性、虛擬化、WSL 這三件事列成前置條件。你如果是在幫團隊做 onboarding，這些東西要跟下載連結放在同一份文件，別藏在沒人看的 wiki 深處。

• 先確認 Windows 版本符合 Docker Desktop 要求。
• 檢查虛擬化是否啟用，Windows 功能是否可用。
• 常用機器要定期更新 WSL kernel，別讓它停在舊狀態。

重開機不是建議，是流程的一部分

官方文件寫「you may be prompted to restart your machine」，我看到這句通常會直接翻成：你大概率就是要重開。Windows 這套東西只要碰到 WSL 或虛擬化，很多變更都不是即時生效。你不重開，後面就會看到一堆半套狀態，然後開始懷疑安裝器有問題。

我以前很愛跳過重開機，因為我想快點把事情做完。結果通常是晚點花更多時間查錯。這件事在 Windows 上特別明顯。Docker Desktop 也一樣，你如果把重開當成可選項，後面常常會遇到一些很詭異的失敗，重開一次就沒事，然後你還要假裝自己剛剛沒有白忙。

實操寫法：安裝 WSL、安裝 Docker Desktop、照提示重開，再開始做任何正式測試。你如果在寫公司內部文件，請直接把「需要重開」寫死，不要寫得像禮貌性提醒。開發者看到「可選」兩個字，多半就會先跳過。

重開後，先開 Docker Desktop 看 engine 狀態，再跑一個最小容器測試。托盤圖示亮綠燈不代表什麼，只有真的跑過容器才算數。

官方文件要看，但要用 sysadmin 的腦袋看

我對 Docker Docs 的態度一直很一致：它有用，但你不能把它當流程書。它比較像產品頁包著文件外皮，該給你的連結有給，該提示的依賴也有提示，但它不會替你整理成一條最短路徑。這就是為什麼很多人照著看還是會卡。

所以我讀這類文件的方式很粗暴：先找依賴鏈，再找順序，最後把裝飾性文字丟掉。對 Windows 上的 Docker Desktop 來說，真正的順序只有四步：先更新或安裝 WSL，再重開機，接著裝 Docker Desktop，最後驗證 runtime。這條順序一旦亂掉，就很容易出現「裝好了但不能用」的狀態。

實操寫法：把官方文件當來源，不要當工作流。你自己的團隊文件要自己整理成 checklist。尤其是多台 Windows 開發機的環境，最好把 WSL 放到基礎映像或 onboarding 文件裡，別讓每個人都重新踩一次坑。

• 讀文件時先抓依賴，不要先看按鈕。
• 把 vendor 文件翻成你自己的步驟表。
• 安裝和驗證分開寫，不要混成一坨。

驗證比自我感覺良好重要

Docker Desktop 裝完之後，我從來不會只看它有沒有開起來。UI 正常不代表 backend 正常，尤其在 Windows 上，很多失敗都是部分成功：程式開了、WSL 也在、但容器就是跑不起來。這種情況最容易讓人誤判。

所以我的習慣是，安裝完、重開完，立刻跑一個真的容器測試。你要驗證的是 runtime，不是圖示。這一步很重要，因為你現在還記得剛剛改了哪些東西，出問題時也比較容易回頭查。拖太久再驗證，記憶就散了，最後只剩下「我好像有裝過」這種模糊印象。

實操寫法：打開 PowerShell 或你慣用的終端機，先看 WSL 狀態，再看 Docker 版本，最後跑一個 hello-world 容器。只要這一步過了，才算真的裝好。失敗的話，先修平台，不要急著碰你的 app stack。

如果你是寫給團隊看的文件，驗證指令要跟安裝步驟放在同一頁。少一個頁面，少一個人偷懶。

我會怎麼交代給同事

如果今天是我交接給同事，我會把話講得很短：先把 WSL 更新好，再裝 Docker Desktop，重開機，最後跑容器驗證。其他細節都先不要管，因為這四步沒過，後面討論什麼 image、volume、network 都是空談。

這種講法聽起來很土，但土的方法最耐用。Windows 上的 Docker 安裝最怕的就是文件寫得太漂亮，結果新人照著做還是卡在半套狀態。你只要把流程壓到最短，問題就比較容易定位，也比較容易重現。

實操寫法：把安裝流程寫成固定模板，讓每台機器、每個新同事都照同一套做。能重複，才有資格叫流程。不能重複的東西，只是一次性的運氣。

可抄的模板

# Docker Desktop on Windows install checklist

## 先做這些
- 確認 Windows 支援 WSL 2
- 先安裝或更新 WSL
- 如果系統提示，先重開機

## 安裝 Docker Desktop
- 從官方 Docker Docs 下載 Windows 版 Docker Desktop
- 執行安裝程式
- 照環境接受必要提示
- 讓安裝完整跑完

## 安裝後
- 如果有提示，立刻重開機
- 開啟 Docker Desktop，等 engine 變成 healthy
- 用真的容器跑一次驗證

## 快速驗證
powershell
wsl --status
docker version
docker run --rm hello-world


## 如果怪怪的
- 再確認 WSL 是否已安裝、版本是否正確
- 再確認虛擬化是否啟用
- 每次改 host 層設定後都重開一次
- 先驗證通過，再碰你的 app stack

## 團隊 onboarding 註記
- WSL 要排在 Docker Desktop 前面
- 不要把 Docker Desktop 寫成 Windows 上的獨立安裝
- 驗證指令要跟安裝步驟放同一份文件

這份拆解的原始來源是 Docker Docs：Install Docker Desktop on Windows。我前面的整理是把官方頁面和它連到的 WSL 資訊重新排成可執行流程，屬於衍生整理，不是官方 checklist。

WSL 的部分我也對照了 Microsoft 的 WSL 安裝指南 和 WSL GitHub Releases。如果你要最短路徑，先看這兩個，再回來裝 Docker Desktop，會少很多冤枉路。