Docker Desktop 無法連接 WSL 2 怎麼辦:命令缺失、引擎啟動與整合排查

從 Windows、WSL 發行版與 Docker Engine 三層排查 Docker Desktop 整合故障,處理 docker 命令缺失、連線失敗、WSL 啟動錯誤、發行版設定和掛載問題。

如果 Windows 終端機可以執行 docker,但 Ubuntu 顯示 command not found,通常是該發行版尚未啟用 Docker Desktop 的 WSL 整合。如果命令存在卻出現 Cannot connect to the Docker daemon,先檢查 Docker Desktop 是否已啟動、目前使用哪個 Docker context,以及是否設定了 DOCKER_HOST。先用唯讀命令找出故障層,再依症狀處理;不要一開始就重設 Docker 資料或註銷 WSL 發行版。

本文適用於 Windows 上的 Docker Desktop、WSL 2 Linux 發行版與 Linux 容器工作流程。Docker Desktop 的 WSL 2 後端、Docker VMM 與 Hyper-V 行為不同,請先確認使用哪一種。Windows 容器模式也不同於本文討論的 Linux 容器環境。

先確認是 Windows、WSL 還是 Docker Engine 出錯

先在 Windows PowerShell 收集基本狀態:

1
2
3
4
5
6
wsl --status
wsl --version
wsl --list --verbose
Get-Command docker -ErrorAction SilentlyContinue
docker context show
docker version

這些命令不會修改容器或發行版。wsl --list --verbose 會顯示每個發行版使用 WSL 1 或 WSL 2;docker version 分成 Client 和 Server 兩部分。若只有 Client、沒有 Server,代表 Docker CLI 找到了,但尚未連上 Engine。

接著進入平常開發使用的 Linux 發行版檢查:

1
2
3
4
5
printf 'distro=%s\n' "$WSL_DISTRO_NAME"
command -v docker || true
type -a docker 2>/dev/null || true
docker context show
docker version

將兩邊結果一起比較,避免把「Windows 找不到程式」、「發行版沒有取得 CLI」和「Engine 沒有回應」混為一談。接下來依這個判斷選擇排查分支。

先確認 WSL 本身可以正常運作

如果 wsl --status、wsl -l -v 或 Ubuntu 啟動本身就失敗,先處理 WSL 和 Windows 虛擬化元件,暫時不要更改 Docker Desktop 設定。

Docker 目前列出的 Docker Desktop WSL 2 後端最低需求是 WSL 2.1.5,並建議保持 WSL 更新。檢查本機版本:

1
2
3
wsl --version
wsl --status
wsl --list --verbose

如果 WSL 太舊,先儲存正在編輯的檔案,再更新並重新啟動 WSL 虛擬機器:

1
2
wsl --update
wsl --shutdown

wsl --shutdown 會立即停止所有執行中的 WSL 發行版。重新啟動 Ubuntu 後,再執行 wsl -l -v,確認目標發行版的 VERSION 欄位是 2。若顯示 1,不要在未備份重要檔案前轉換;轉換可能耗時,也可能失敗。

如果 WSL 更新失敗,檢查 Microsoft Store、Windows Update 和網路政策。wsl --update --web-download 會改用網頁下載方式。更新期間不要強制關閉 Windows,也不要把 wsl --unregister 當成一般重新啟動命令。

確認 Docker Desktop 已啟動,且正在使用 Linux 容器模式

在 Windows 工作列通知區確認 Docker Desktop 已完成啟動。如果狀態一直顯示 Starting 或 Docker Engine is starting,或畫面出現 Engine 錯誤,先記錄完整訊息。通知區選單若顯示「Switch to Linux containers」,目前可能是 Windows 容器模式;WSL Linux 容器開發需要切換到 Linux 容器。

只有在相容的後端與容器模式下,WSL 整合選項才會出現。Docker Desktop 使用 WSL 2 engine 時,開啟 Settings > General,確認「Use the WSL 2 based engine」;再到 Settings > Resources > WSL Integration,為需要的發行版啟用整合並選擇 Apply。

如果安裝了多個發行版,預設發行版未必是目前開啟的那一個。執行 wsl -l -v 查看實際名稱,並在整合頁面選取正確的發行版。需要變更預設發行版時,執行:

1
wsl --set-default Ubuntu

將 Ubuntu 換成清單中顯示的名稱。變更預設值只會影響未指定發行版名稱的 WSL 命令;它不會把其他發行版轉成 WSL 2,也不會搬移檔案。

WSL 顯示找不到 docker 命令

若 Windows PowerShell 中的 docker version 正常,但 Linux 發行版顯示 command not found,依序檢查:

  1. 在 wsl -l -v 中確認目標發行版版本為 2。
  2. 在 Docker Desktop 設定中啟用 WSL 2 engine。
  3. 到 Settings > Resources > WSL Integration 啟用目前的發行版。
  4. 選擇 Apply,等待 Docker Desktop 套用完成。
  5. 從 Windows 執行 wsl --shutdown,再重新開啟發行版。
  6. 在發行版中執行 command -v docker 和 docker version。

不要只因命令不存在,就在發行版中再安裝一套 Docker Engine。Docker 官方提醒,在 WSL 發行版直接安裝 Docker Engine 或 Docker CLI 可能與 Docker Desktop 整合衝突。兩套安裝也可能讓 CLI 連到不同的 daemon,導致 Ubuntu 和 Windows 顯示不同的容器清單。

在 Linux 發行版內獨立執行 Engine 是另一種部署選擇。請明確決定由誰管理 daemon、資料目錄、啟動服務和 Docker context;不要讓兩個 Engine 同時競爭同一組開發命令。

命令存在,但無法連接 Docker daemon

先確認 Windows 上的 Docker Desktop 已完全啟動,再執行:

1
2
3
docker context ls
docker context show
docker version

如果目前 context 指向 SSH 遠端主機或其他端點,docker 可能連到的不是本機 Desktop。確認後再切換到 Desktop 對應的 context。不要盲目覆寫 Docker 設定;遠端 context 可能是刻意設定的。

在 WSL 中檢查環境變數是否覆寫連線位址:

1
2
3
env | grep -E '^DOCKER_(HOST|CONTEXT|TLS|CERT_PATH)=' || true
docker context ls
docker context show

DOCKER_HOST 可以強制 CLI 使用指定的 socket 或 TCP 位址;DOCKER_CONTEXT 也可能選擇其他 context。先記下變數值與來源,再決定是否在目前終端機暫時移除。PowerShell 可檢查:

1
Get-ChildItem Env:DOCKER_HOST,Env:DOCKER_CONTEXT -ErrorAction SilentlyContinue

不要把 sudo docker 當成連線問題的通用解法。它可能改用 root 使用者自己的 Docker 設定與 context,因而連到另一個 daemon。遇到權限錯誤時,先確認目前使用哪個 Docker CLI 和 Engine。

如果 Docker Desktop Engine 還在啟動,重試 Compose 命令只會重複失敗。先等 Dashboard 顯示引擎就緒,再用 docker version 確認 Server 資訊,最後才執行專案命令。

命令可連線,但看到的容器不符合預期

這通常代表 CLI 連到了另一套 Engine。先檢查 context 和執行檔解析結果:

1
2
3
4
Get-Command docker -All
where.exe docker
docker context ls
docker context show

在 WSL 中執行:

1
2
3
type -a docker
command -v docker
env | grep -E '^DOCKER_(HOST|CONTEXT|TLS|CERT_PATH)=' || true

如果 type -a docker 列出多個路徑,確認第一個執行檔的來源。透過 Windows PATH 注入的 Docker Desktop CLI、發行版內安裝的 CLI 和 shell alias 可能同時存在。先辨識來源,再考慮移除檔案或修改系統 PATH。

容器、映像和 volume 都屬於各自的 Engine。切換 context 後,docker ps -a 或 docker volume ls 顯示不同結果是正常現象。清理任何資料前先確認目前端點,避免把遠端正式環境誤認成本機測試 Engine。

出現 WSL 意外錯誤或虛擬機器啟動失敗

如果錯誤包含 HCS_E_HYPERV_NOT_INSTALLED 或 ERROR_NOT_SUPPORTED,或 WSL 本身也無法啟動發行版,先檢查 Windows 功能和硬體虛擬化:

  • BIOS/UEFI 中的 CPU 虛擬化是否已啟用。
  • Windows 是否啟用了 Virtual Machine Platform 和 Windows Subsystem for Linux。
  • Windows 若執行在虛擬機或雲端桌面中,宿主機是否啟用巢狀虛擬化。
  • Hypervisor 是否被開機設定或其他虛擬化軟體停用。
  • 最近是否安裝 Android 模擬器或舊版虛擬機軟體,並改變 Hyper-V 設定。

可在工作管理員「效能 > CPU」查看虛擬化狀態。不了解目前虛擬機設定時,不要直接修改 BCD 或 Windows 功能。受管理的裝置也應先確認組織政策。

若 wsl -l -v 正常,只有 Docker Desktop 的 docker-desktop 發行版異常,請保存完整錯誤和時間戳,再透過 Docker Desktop 的 Troubleshoot > Get support 收集診斷。不要手動刪除 docker-desktop 或 docker-desktop-data,也不要在其中執行清理命令。

WSL 整合選單不見,或選了發行版仍然無效

先確認 Docker Desktop 不在 Windows 容器模式,再確認使用的虛擬機器後端。Docker 官方文件說明,完整 WSL Integration 只支援 WSL 2 engine。Docker VMM 模式的近期版本可從 WSL 發行版執行 Docker CLI,但 socket、直接掛載和開發工具支援的界線不同。

變更後端前,先閱讀目前 Docker Desktop 版本的設定文件,並確認團隊工具需要哪些功能。docker 命令能執行,不代表依賴 Docker Engine API socket 的 VS Code Dev Containers、Docker SDK 或 Testcontainers 都相容。

如果剛啟用整合,但終端機仍使用舊環境,執行:

1
wsl --shutdown

再重新開啟目標發行版。這會關閉所有發行版和 WSL 虛擬機器,不會重設檔案,但會中斷尚未儲存的程序狀態。

不要為了刷新整合而來回切換 WSL 1/2、註銷發行版、將 Docker Desktop 恢復原廠設定或刪除虛擬磁碟。這些操作可能造成資料遺失,通常也不是第一輪排查所需。

Docker VMM 中命令能用,但掛載或開發工具不能用

Docker VMM 與 WSL 2 engine 的互動方式不同。在 VMM 模式下,WSL 可透過 Windows interop 呼叫 Docker CLI;但目前文件列出的限制包括:發行版內沒有 Linux Docker socket,且只能直接 bind mount Windows 磁碟中的檔案。依賴 socket 的 Docker SDK、Testcontainers 和 Dev Containers 可能無法運作。

從 PowerShell 啟動的專案通常使用 C:\... 路徑;同一個 Windows 磁碟在 WSL 中會顯示為 /mnt/c/...。若錯誤指向發行版內的 /home/...,而你正在使用 Docker VMM,先確認該工作流程是否受支援。不要假設把 Linux 路徑改成 Windows 路徑後,權限、檔案監看和效能就完全相同。

使用 WSL 2 engine 進行 Linux 開發時,Docker 建議將專案放在 Linux 發行版的檔案系統中,以減少跨檔案系統操作。如果 Windows 工具與 Linux 容器必須頻繁存取同一專案,應先評估權限、大小寫、檔案監看和掛載效能,再選定主要工作目錄。

掛載失敗時,先確認來源路徑是否存在、命令從哪個目錄執行、目前使用哪種後端,以及目標發行版是否已啟用整合。請區分容器路徑 /app、Windows 路徑 C:\project 和 WSL 路徑 /mnt/c/project。

WSL 有發行版,但 Docker Desktop 找不到

從 Windows 再次列出發行版並檢查版本欄位:

1
2
wsl --list --verbose
wsl --list --quiet

如果發行版名稱有空格或大小寫不同,請使用命令輸出中的原名選取。新安裝的發行版可能預設為 WSL 1;Docker Desktop 的 WSL 2 整合需要 WSL 2 發行版。轉換前先備份:

1
2
wsl --export Ubuntu "$env:USERPROFILE\Desktop\Ubuntu-backup.tar"
wsl --set-version Ubuntu 2

匯出檔包含發行版資料,可能占用大量磁碟空間。轉換前確認備份檔已建立且可讀取。不要將範例名稱直接套用到名稱不同的重要發行版。

如果曾重新命名、搬移或匯入發行版,先用 wsl -l -v 確認註冊名稱和狀態。不要透過刪除註冊資料讓它「重新出現」。發行版註冊、磁碟檔案與 Docker Desktop 管理的虛擬磁碟是不同物件。

Docker Desktop 更新後整合突然失效

更新後不要立刻清除所有映像和容器。先記錄 Docker Desktop 版本、wsl --version、發行版名稱、後端模式和完整錯誤,再查看 Docker 官方發行說明是否提到相同版本組合。

Docker 近期發行說明記錄過一項問題:在 WSL 2.6.x 及更新版本上,使用者發行版整合可能因零位元組代理程式而失效,並出現 Permission denied 或 Exec format error;之後的版本已修復。如果錯誤相符,先確認實際 Docker Desktop 版本和更新管道,不要照論壇指示手動替換內部檔案。

同一份發行說明也記錄了 Resource Saver 停止虛擬機後,整合發行版中的 Docker CLI 暫時失效的修復。是否適用取決於實際版本;不要只憑關鍵字判斷。診斷 ID 和可重現步驟比猜測版本更有用。

可以將重現流程縮短為:完全結束 Docker Desktop、執行 wsl --shutdown、重新啟動 Docker Desktop、等待 Engine 就緒、只開啟一個目標發行版,再執行 docker version。逐步記錄時間和輸出。若只有一個發行版失敗,就聚焦該發行版;若所有 WSL 命令都失敗,回到 WSL 和 Windows 功能檢查。

一次只變更一個設定。例如先更新 WSL 並確認結果,再考慮切換 Docker Desktop 後端。一次更新 WSL、切換 Hyper-V/VMM、清除資料和重新安裝,會失去問題因果線索,也可能引入新變因。

懷疑回歸問題時,先核對 Docker Desktop About 頁面和官方發行說明日期,再依組織政策決定更新或回退。不要從不明來源下載舊安裝程式,也不要用論壇腳本覆寫 docker-desktop 內部檔案。

拉取映像失敗,不一定是 WSL 整合故障

若 docker version 已顯示 Server,但 docker pull 出現 DNS、代理、TLS 或驗證錯誤,CLI 通常已連上 Engine。此時應檢查 Windows 網路、Docker Desktop 代理、Registry 憑證和 Registry 位址,而非反覆切換 WSL 整合。

先執行不會拉取新映像的狀態檢查,並保存完整錯誤。若問題只在公司網路或啟用 VPN 時發生,請在相同網路條件下比較 DNS、代理政策和企業憑證要求。不要為了測試而關閉公司安全代理或略過憑證驗證。

docker compose up 失敗也可能來自專案設定或容器應用程式。先執行 docker compose config 檢查解析後的 Compose 檔,再確認故障發生在映像拉取、容器建立、volume 掛載還是應用程式啟動階段。只有命令無法連接 daemon 時,才繼續走 WSL 整合分支。

如果 Engine 已連線,但 Compose 環境變數沒有進入容器,可參考 Docker Compose 環境變數排查指南;如果問題是資料庫尚未就緒或服務啟動順序,請看 Compose depends_on 與 healthcheck 指南。

磁碟空間、重設與備份界線

Docker Desktop 的 WSL 2 engine 資料通常位於使用者目錄中的 Docker WSL 資料位置,但位置可能已在設定中變更。刪除該虛擬磁碟可能永久移除本機映像、容器和 volume 資料。Clean up data 與 Reset to factory defaults 也不是無損的重新啟動選項。

清理前,確認需要保留的資料庫 volume、映像或容器資料已有獨立備份。容器可以重建,不代表 volume 資料也能重建。企業環境請先檢查保留和備份政策。

優先使用 Docker Desktop 的診斷、正常結束和重新啟動流程。只有了解清理範圍並確認備份可用後,才考慮清除資料或恢復原廠設定。

收集診斷資訊並驗證修復

Docker Dashboard 可以開啟時,在 Troubleshoot 選單選擇 Get support。等待診斷收集完成後上傳並保存 Diagnostic ID。如果介面無法啟動,可依安裝方式使用官方 docker desktop diagnose 命令;命令列支援情況取決於 Docker Desktop 版本。

回報問題時附上以下資料,而不只寫「Docker 壞了」:

  • Windows 和 Docker Desktop 版本。
  • wsl --version、wsl --status 與 wsl -l -v 的輸出。
  • 目標發行版名稱、WSL 版本和 Docker Desktop 後端。
  • PowerShell 與 WSL 中 docker version 的完整輸出。
  • docker context show 輸出,以及是否設定 DOCKER_HOST 或 DOCKER_CONTEXT。
  • 完整錯誤、首次出現時間、之前是否更新,以及 Diagnostic ID。

修復後,分別在 PowerShell 和目標 WSL 發行版驗證:

1
2
docker version
docker context show
1
2
3
command -v docker
docker version
docker context show

只有兩個終端都連到預期的本機 Engine,且 docker version 顯示 Client 與 Server 資訊,才算完成整合驗證。接著再執行 docker compose config 和專案啟動命令,確認掛載、網路和環境變數都符合預期。

常見問題

Windows 中 Docker 正常,但 Ubuntu 沒有 docker 命令,需要重裝嗎?

先啟用 Docker Desktop 的 WSL 2 engine 與 Ubuntu 整合,再關閉並重新開啟 WSL。不要把在 Ubuntu 安裝第二套 Docker Engine 當成第一步。

docker version 只顯示 Client 代表什麼?

CLI 已執行,但尚未收到 Engine Server 回應。檢查 Docker Desktop 啟動狀態、目前 context、DOCKER_HOST 和後端模式。

執行 wsl --shutdown 會刪除容器嗎?

它會停止所有 WSL 發行版和 WSL 虛擬機器,不是刪除資料的命令。不過執行中程式尚未儲存的狀態會中斷。之後重新啟動 Docker Desktop 和目標發行版再驗證。

可以刪除 docker-desktop-data 修復啟動問題嗎?

不要把刪除內部發行版當成一般修復。這可能清除本機映像、容器或 volume。先收集診斷並查看官方復原步驟,確認備份後才考慮資料層級的操作。

為什麼 WSL 中 docker 能執行,Dev Containers 或 Testcontainers 卻失敗?

命令可執行不代表 Docker socket 和 Engine API 的所有使用方式都支援。先確認 Docker Desktop 後端;Docker VMM 有不同的 socket 和掛載限制。

官方資料