Docker Desktop 的疑難排解主題

提示

如果在疑難排解中找不到解決方案，請瀏覽 GitHub 儲存庫或建立新的問題

• docker/for-mac
• docker/for-win
• docker/for-linux

適用於所有平台的主題

確保憑證已正確設定

Docker Desktop 會忽略不安全儲存庫下列出的憑證，且不會將用戶端憑證傳送給它們。 嘗試從儲存庫提取映像檔的指令（例如 docker run）會在命令列上產生錯誤訊息，如下所示：

Error response from daemon: Get http://192.168.203.139:5858/v2/: malformed HTTP response "\x15\x03\x01\x00\x02\x02"

以及在儲存庫上。 例如：

2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52882: tls: client didn't provide a certificate
2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52883: tls: first record does not look like a TLS handshake

Docker Desktop 的 UI 顯示為綠色、扭曲或出現視覺偽影

Docker Desktop 預設使用硬體加速圖形，這可能會導致某些 GPU 出現問題。 在這種情況下，Docker Desktop 將會成功啟動，但某些畫面可能會顯示為綠色、扭曲或出現一些視覺偽影。

要解決此問題，請在 Docker Desktop 的 settings-store.json 檔案（或 Docker Desktop 4.34 及更早版本的 settings.json）中建立 "disableHardwareAcceleration": true 項目來停用硬體加速。 你可以在以下位置找到此檔案：

• Mac：~/Library/Group Containers/group.com.docker/settings-store.json
• Windows：C:\Users\[USERNAME]\AppData\Roaming\Docker\settings-store.json
• Linux：~/.docker/desktop/settings-store.json

更新 settings-store.json 檔案後，請關閉並重新啟動 Docker Desktop 以套用變更。

適用於 Linux 和 Mac 的主題

掛載磁碟區需要針對 $HOME 以外的任何專案目錄進行檔案共享

如果你正在使用掛載的磁碟區，並且收到執行階段錯誤，指出找不到應用程式檔案、拒絕存取磁碟區掛載或服務無法啟動（例如使用 Docker Compose 時），你可能需要開啟 檔案共享。

掛載磁碟區需要針對位於 /home/<user> 目錄以外的專案使用共享磁碟機。 從「設定」中，選擇「資源」，然後選擇「檔案共享」。 共享包含 Dockerfile 和磁碟區的磁碟機。

Docker Desktop 無法在 MacOS 或 Linux 平台上啟動

在 MacOS 和 Linux 上，Docker Desktop 會建立用於行程間通訊的 Unix 網域通訊端。

如果任何這些 socket 的絕對路徑長度超過作業系統限制（MacOS 為 104 個字元，Linux 為 108 個字元），Docker 將無法啟動。這些 socket 建立在使用者的家目錄下。如果使用者 ID 長度導致 socket 的絕對路徑超過作業系統的路徑長度限制，則 Docker Desktop 無法建立 socket 並且無法啟動。解決方法是縮短使用者 ID，我們建議在 MacOS 上最大長度為 33 個字元，在 Linux 上最大長度為 55 個字元。

以下是 MacOS 上的錯誤範例，指出啟動失敗是由於超過上述的作業系統限制所致

[vpnkit-bridge][F] listen unix <HOME>/Library/Containers/com.docker.docker/Data/http-proxy-control.sock: bind: invalid argument

[com.docker.backend][E] listen(vsock:4099) failed: listen unix <HOME>/Library/Containers/com.docker.docker/Data/vms/0/00000002.00001003: bind: invalid argument

適用於 Mac 的主題

偵測到不相容的 CPU

Docker Desktop 需要支援虛擬化的處理器 (CPU)，更具體地說，需要支援 Apple Hypervisor framework。Docker Desktop 僅與 CPU 支援 Hypervisor framework 的 Mac 系統相容。如 Apple Hypervisor Framework 文件中關於支援的硬體所述，大多數 2010 年及之後生產的 Mac 都支援它。

一般來說，支援包含延伸分頁表 (EPT) 和非限制模式的 Intel VT-x 功能集的機器都受支援。

若要檢查您的 Mac 是否支援 Hypervisor framework，請在終端機視窗中執行以下指令。

$ sysctl kern.hv_support

如果您的 Mac 支援 Hypervisor Framework，該指令會顯示 kern.hv_support: 1。

如果不支援，該指令會顯示 kern.hv_support: 0。

另請參閱 Apple 文件中的 Hypervisor Framework 參考。

VPNKit 持續中斷

在 Docker Desktop 4.19 版中，gVisor 取代了 VPNKit，以增強在 macOS 13 及更高版本上使用虛擬化架構時的 VM 網路效能。

要繼續使用 VPNKit，請將 "networkType":"vpnkit" 新增到位於 ~/Library/Group Containers/group.com.docker/settings-store.json 的 settings-store.json 檔案中。

適用於 Windows 的主題

磁碟區

共用磁碟區的資料目錄權限錯誤

從 Windows 共用檔案時，Docker Desktop 會將 共用磁碟區 的權限設定為預設值 0777。

磁碟區掛載需要 Linux 容器的共用資料夾

如果您正在使用掛載的磁碟區，並且收到執行階段錯誤，指出找不到應用程式檔案、拒絕存取磁碟區掛載或服務無法啟動（例如使用 Docker Compose 時），您可能需要開啟 共用資料夾。

使用 Hyper-V 後端時，從 Windows 掛載檔案需要 Linux 容器的共用資料夾。從**設定**中，選擇**共用資料夾**並共用包含 Dockerfile 和磁碟區的資料夾。

符號連結支援

符號連結在容器內部和跨容器運作。如需詳細資訊，請參閱 符號連結在 Windows 上如何運作？。

避免非預期的語法錯誤，請對容器中的檔案使用 Unix 樣式換行符號

任何要在容器內執行的檔案都必須使用 Unix 樣式 \n 換行符號。這包括在建置的指令列和 Docker 檔案中 RUN 指令所參考的檔案。

Docker 容器和 docker build 在 Unix 環境中執行，因此容器中的檔案必須使用 Unix 樣式換行符號：\n，*而不是* Windows 樣式：\r\n。使用 Windows 工具撰寫檔案（例如 shell 指令碼）時，請記住這一點，因為預設值可能是 Windows 樣式換行符號。這些指令最終會傳遞給基於 Unix 的容器內的 Unix 指令（例如，傳遞給 /bin/sh 的 shell 指令碼）。如果使用 Windows 樣式換行符號，docker run 將因語法錯誤而失敗。

有關此問題和解決方案的範例，請參閱 GitHub 上的此問題：Docker RUN 無法執行 shell 指令碼

在 Linux 上，系統會處理將路徑掛載到另一個路徑的工作。例如，當您在 Linux 上執行以下指令時

$ docker run --rm -ti -v /home/user/work:/work alpine

它會在目標容器中新增一個 /work 目錄來鏡像指定的路徑。

但是，在 Windows 上，您必須更新來源路徑。例如，如果您使用的是舊版 Windows shell (cmd.exe)，您可以使用以下指令

$ docker run --rm -ti -v C:\Users\user\work:/work alpine

這會啟動容器並確保磁碟區變得可用。這是可能的，因為 Docker Desktop 會偵測 Windows 樣式路徑，並提供適當的轉換來掛載目錄。

Docker Desktop 也允許您使用 Unix 樣式路徑到適當的格式。例如

$ docker run --rm -ti -v /c/Users/user/work:/work alpine ls /work

使用 Git Bash

Git Bash (或 MSYS) 在 Windows 上提供 Unix 類似環境。這些工具會在指令列上套用自己的預處理。例如，如果您在 Git Bash 中執行以下指令，它會產生錯誤

$ docker run --rm -ti -v C:\Users\user\work:/work alpine
docker: Error response from daemon: mkdir C:UsersUserwork: Access is denied.

這是因為 \ 字元在 Git Bash 中具有特殊含義。如果您使用的是 Git Bash，則必須使用 \\ 將其取消

$ docker run --rm -ti -v C:\\Users\\user\\work:/work alpine

此外，在指令碼中，使用 pwd 指令來避免硬編碼檔案系統位置。其輸出是 Unix 樣式路徑。

$ pwd
/c/Users/user/work

與 $() 語法結合使用時，以下指令在 Linux 上有效，但在 Git Bash 上會失敗。

$ docker run --rm -ti -v $(pwd):/work alpine
docker: Error response from daemon: OCI runtime create failed: invalid mount {Destination:\Program Files\Git\work Type:bind Source:/run/desktop/mnt/host/c/Users/user/work;C Options:[rbind rprivate]}: mount destination \Program Files\Git\work not absolute: unknown.

您可以使用額外的 / 來解決此問題

$ docker run --rm -ti -v /$(pwd):/work alpine

指令碼的可攜性不受影響，因為 Linux 將多個 / 視為單個項目。單行上的每個路徑都必須取消。

$ docker run --rm -ti -v /$(pwd):/work alpine ls /work
ls: C:/Program Files/Git/work: No such file or directory

在此範例中，由於前面的 '/'，$(pwd) 未轉換。但是，第二個 '/work' 在傳遞給 Docker Desktop 之前會被 POSIX 層轉換。您也可以使用額外的 `/` 來解決此問題。

$ docker run --rm -ti -v /$(pwd):/work alpine ls //work

要驗證錯誤是來自您的指令碼還是來自其他來源，您可以使用環境變數。例如

$ MSYS_NO_PATHCONV=1 docker run --rm -ti -v $(pwd):/work alpine ls /work

它只在此處需要環境變數。值並不重要。

在某些情況下，MSYS 也會將冒號轉換為分號。使用 `~` 時也可能發生類似的轉換，因為 POSIX 層會將其轉換為 DOS 路徑。`MSYS_NO_PATHCONV` 在這種情況下也有效。

虛擬化

您的機器必須具備以下功能才能使 Docker Desktop 正常運作

WSL 2 和 Windows 家用版

1. 虛擬機器平台
2. 適用於 Linux 的 Windows 子系統

   Hyper-V

   在 Windows 10 專業版或企業版上，您也可以使用啟用以下功能的 Hyper-V

   1. Hyper-V 已安裝並正常運作
   2. 在 BIOS 中啟用虛擬化

      Docker Desktop 需要安裝並啟用 Hyper-V 以及 Windows PowerShell 的 Hyper-V 模組。Docker Desktop 安裝程式會為您啟用它。

      Docker Desktop 也需要兩個 CPU 硬體功能才能使用 Hyper-V：虛擬化和二級位址轉譯 (SLAT)，也稱為快速虛擬化索引 (RVI)。在某些系統上，必須在 BIOS 中啟用虛擬化。所需的步驟因廠商而異，但通常 BIOS 選項稱為 Virtualization Technology (VTx) 或類似名稱。執行 systeminfo 命令以檢查所有必要的 Hyper-V 功能。詳情請參閱 Windows 10 上 Hyper-V 的必要條件。

      要手動安裝 Hyper-V，請參閱 在 Windows 10 上安裝 Hyper-V

      除了 Hyper-V 或 WSL 2 之外，還必須開啟虛擬化功能。檢查「工作管理員」上的「效能」索引標籤。或者，您也可以在終端機中輸入 'systeminfo'。如果您看到「Hyper-V 需求：已偵測到 Hypervisor。將不會顯示 Hyper-V 所需的功能」，則表示已啟用虛擬化功能。

      

      如果您手動解除安裝 Hyper-V、WSL 2 或關閉虛擬化功能，Docker Desktop 將無法啟動。

      要開啟巢狀虛擬化，請參閱 在 VM 或 VDI 環境中執行 Docker Desktop for Windows。

      在 Windows 啟動時啟用 Hypervisor

      如果您已完成上述步驟，但仍然遇到 Docker Desktop 啟動問題，這可能是因為已安裝 Hypervisor，但在 Windows 啟動期間未啟動。某些工具（例如舊版 Virtual Box）和電玩遊戲安裝程式會在開機時關閉 Hypervisor。要重新開啟它

      1. 開啟系統管理員主控台提示字元。
      2. 執行 bcdedit /set hypervisorlaunchtype auto。
      3. 重新啟動 Windows。

      您也可以參考 Microsoft TechNet 文章

      如果您正在使用 Hyper-V，並且在 VDI 環境中執行 Docker Desktop 時收到以下錯誤訊息

      The Virtual Machine Management Service failed to start the virtual machine 'DockerDesktopVM' because one of the Hyper-V components is not running
      

      請嘗試啟用巢狀虛擬化。

      Windows 容器和 Windows Server

      Windows Server 不支援 Docker Desktop。如果您對於如何在 Windows 10 上執行 Windows 容器有任何疑問，請參閱 在 Windows 和 Linux 容器之間切換。

      docker/labs

      C:\Program Files\Docker\docker.exe:
       image operating system "linux" cannot be used on this platform.
       See 'C:\Program Files\Docker\docker.exe run --help'.