Dev Containers 訣竅與技巧

本文包含一些訣竅與技巧，協助您在不同環境中設定並執行 Dev Containers 擴充功能。

安裝 Docker 的替代方式

您可以透過幾種方式將 Docker 與 Dev Containers 擴充功能搭配使用，包括

安裝於本機的 Docker。
安裝在遠端環境中的 Docker。
其他符合 Docker 標準的 CLI，安裝於本機或遠端。
- 雖然其他 CLI 可能有效，但並非官方支援。請注意，附加至 Kubernetes 叢集僅需要妥善設定的 kubectl CLI。

您可以在 Docker 替代選項說明文件中了解更多資訊。

自訂 AI 聊天回應

自訂指令可讓您描述通用的準則或規則，以獲得符合您特定編碼習慣與技術堆疊的回應。

您可以在開發容器中使用自訂指令，為 Copilot 提供更多關於您所連線開發容器類型的資訊（例如安裝了哪些語言或工具鏈）。您可以透過幾種方式達成

直接在您的 devcontainer.json 中新增 "github.copilot.chat.codeGeneration.instructions"
- 我們發布了開發容器資源（例如映像檔和功能 (Features)），以簡化建立與連線至開發容器的過程，我們現在也在這些檔案中包含了自訂指令。
- 此處是 Python 功能中自訂指令的範例。
像在本機上一樣使用 copilot-instructions.md 檔案

Windows 版 Docker Desktop 訣竅

Docker Desktop for Windows 在大多數設定中運作良好，但仍有一些可能會導致問題的「潛在陷阱」。以下是避免這些問題的幾項技巧

請考慮在 Windows 10 (2004+) 上使用新的 Docker WSL 2 後端。 如果您正在使用 Docker Desktop 的 WSL 2 後端，則可以使用它來開啟 WSL 內以及本機的資料夾。容器也會在 Windows 與 WSL 之間共用，且這個新引擎較不容易出現檔案共用問題。詳情請參閱快速入門。
切換出「Linux Containers on Windows (LCOW)」模式。 雖然預設為停用，但新版的 Docker 支援 Linux Containers on Windows (LCOW)，讓您可以同時使用 Windows 與 Linux 容器。然而，由於這是新功能，您可能會遇到問題，且 Dev Containers 擴充功能目前僅支援 Linux 容器。您可以隨時在 Docker 工作列圖示上按一下右鍵，並從內容選單中選擇切換至 Linux 容器... (Switch to Linux Containers...) 來退出 LCOW 模式。
請確保您的防火牆允許 Docker 設定共用磁碟機。 Docker 只需要在本機兩個 IP 之間進行連線，但某些防火牆軟體可能會阻擋任何磁碟機共用或所需的連接埠。

以下是一些適用於舊版 Docker for Windows 的技巧，但這些問題目前應已解決。如果您因為可能的退化（regression）而遇到奇怪的行為，過去這些技巧曾解決過相關問題。

共用磁碟機時，請使用 AD 網域帳戶或本機管理員帳戶。請勿使用 AAD (以電子郵件為基礎) 帳戶。 AAD 帳戶已知有相關問題，記錄於 Docker 問題 #132 與問題 #1352 中。如果您必須使用 AAD 帳戶，請在您的機器上建立一個單純用於磁碟機共用的本機管理員帳戶。請依照這篇部落格文章中的步驟來進行設定。
堅持使用英數密碼以避免磁碟機共用問題。 當系統要求您在 Windows 上共用磁碟機時，系統會提示您輸入機器上具有管理員權限之帳戶的使用者名稱與密碼。如果您收到關於使用者名稱或密碼不正確的警告，這可能是因為密碼中包含特殊字元。例如，已知 !、[ 和 ] 會造成問題。請將您的密碼變更為純英數組合來解決。詳情請參閱關於 Docker 磁碟區掛載問題的討論。
請使用您的 Docker ID 登入 Docker（而非電子郵件）。 Docker CLI 僅支援使用您的 Docker ID，因此使用電子郵件可能會導致問題。詳情請參閱 Docker 問題 #935。

如果您仍有問題，請參閱 Docker Desktop for Windows 疑難排解指南。

VS Code Dev Containers 擴充功能僅能在您的程式碼位於與 Docker 共用的資料夾或磁碟機中時，自動將原始程式碼掛載至容器內。如果您從非共用的位置開啟開發容器，容器會成功啟動，但工作區將會是空的。

請注意，在使用 Docker Desktop 的 WSL 2 引擎時，不需要執行此步驟。

若要變更 Docker 的磁碟機與資料夾共用設定

Windows

在 Docker 工作列圖示上按一下右鍵，並選擇設定 (Settings)。
前往 資源 (Resources) > 檔案共用 (File Sharing)，並勾選您存放原始程式碼的磁碟機。
如果您看到關於本機防火牆阻擋共用動作的訊息，請參閱這篇 Docker KB 文章以取得後續步驟。

macOS

按一下 Docker 選單列圖示，並選擇偏好設定 (Preferences)。
前往 資源 (Resources) > 檔案共用 (File Sharing)。確認包含您原始程式碼的資料夾在所列出的共用資料夾中。

解決容器中的 Git 換行符號問題（導致大量檔案被修改）

由於 Windows 和 Linux 使用不同的預設換行符號，Git 可能會報告大量檔案被修改，儘管它們除了換行符號之外沒有任何差異。為了防止這種情況，您可以使用 .gitattributes 檔案，或在 Windows 端進行全域設定，以停用換行符號轉換。

通常，在您的儲存庫中新增或修改 .gitattributes 檔案是解決此問題最可靠的方法。將此檔案提交到原始碼控制中將有助於他人，並允許您根據儲存庫適當調整行為。例如，將以下內容新增至儲存庫根目錄的 .gitattributes 檔案中，將強制所有檔案為 LF，但需要 CRLF 的 Windows 批次檔除外

* text=auto eol=lf
*.{cmd,[cC][mM][dD]} text eol=crlf
*.{bat,[bB][aA][tT]} text eol=crlf

請注意，這適用於 Git v2.10+，因此如果您遇到問題，請確保您安裝的是最新版的 Git 客戶端。您可以在同一個檔案中新增儲存庫中其他需要 CRLF 的檔案類型。

如果您仍然傾向於始終上傳 Unix 風格的換行符號 (LF)，可以使用 input 選項。

git config --global core.autocrlf input

如果您想完全停用換行符號轉換，請改為執行下列指令

git config --global core.autocrlf false

最後，您可能需要再次複製 (clone) 儲存庫，這些設定才會生效。

使用 Docker Compose 時避免在容器中設定 Git

請參閱主容器文章中的與您的容器共用 Git 憑證，以了解解決此問題的資訊。

解決從容器進行 Git push 或同步時的掛起問題

如果您使用 SSH 複製 Git 儲存庫，且您的 SSH 金鑰有密碼保護，VS Code 的提取 (pull) 和同步 (sync) 功能在遠端執行時可能會掛起。

請使用沒有密碼保護的 SSH 金鑰、透過 HTTPS 複製，或從命令列執行 git push 來繞過此問題。

解決關於 Linux 相依套件缺失的錯誤

某些擴充功能依賴特定 Docker 映像檔中沒有的程式庫。請參閱容器文章，了解解決此問題的幾種選項。

加速 Docker Desktop 中的容器

預設情況下，Docker Desktop 僅提供給容器機器資源的一部分。在大多數情況下這已經足夠，但如果您需要更多資源，可以增加記憶體、CPU 或磁碟使用量。

首先，請嘗試停止任何您不再使用的執行中容器。

如果這無法解決您的問題，您可能需要確認 CPU 使用率是否真的是問題所在，或者是否有其他因素。檢查此情況的簡單方法是安裝 Resource Monitor 擴充功能。安裝在容器中時，它會在狀態列提供有關您容器資源的使用資訊。

Resource use Status bar

如果您希望始終安裝此擴充功能，請將此加入您的 settings.json

"dev.containers.defaultExtensions": [
    "mutantdino.resourcemonitor"
]

如果您確定需要提供容器更多機器資源，請遵循下列步驟

在 Docker 工作列圖示上按一下右鍵，並選擇設定 (Settings) / 偏好設定 (Preferences)。
前往 進階 (Advanced) 以增加 CPU、記憶體或交換空間 (Swap)。
在 macOS 上，前往 磁碟 (Disk) 以增加 Docker 允許在您機器上使用的磁碟空間。在 Windows 上，此設定位於「進階」下方與其他設定在一起。

最後，如果您的容器正在執行磁碟密集型作業，或者您只是在尋找更快的回應時間，請參閱提升容器磁碟效能以取得技巧。VS Code 的預設值是針對便利性與通用支援進行最佳化，但仍可進一步優化。

清理未使用的容器與映像檔

如果您看到 Docker 報告磁碟空間不足的錯誤，通常可以透過清理未使用的容器與映像檔來解決。有幾種方法可以做到這一點

選項 1：使用 Remote Explorer

您可以選取 Remote Explorer，在您要移除的容器上按一下右鍵，並選擇 移除容器 (Remove Container) 來刪除容器。

Remote Explorer screenshot

然而，這不會清理您可能已下載的任何映像檔，這可能會造成系統雜亂。

選項 2：使用 Container Tools 擴充功能

在 VS Code 中開啟一個本機視窗 (檔案 > 新視窗)。
如果尚未安裝，請從擴充功能檢視安裝 Container Tools 擴充功能。
接著，您可以前往 Container Explorer 並展開 容器 (Containers) 或 映像檔 (Images) 節點，按一下右鍵，並選擇 移除容器/映像檔 (Remove Container / Image)。

選項 3：使用 Docker CLI 選擇要刪除的容器

開啟本機終端機/命令提示字元（或在 VS Code 中使用本機視窗）。
輸入 docker ps -a 以查看所有容器的清單。
從此清單輸入 docker rm <容器 ID> 來移除容器。
輸入 docker image prune 來移除任何未使用的映像檔。

如果 docker ps 無法提供足夠的資訊來辨識您要刪除的容器，下列指令將列出所有由 VS Code 管理的開發容器，以及用於產生它們的資料夾。

docker ps -a --filter="label=vsch.quality" --format "table {{.ID}}\t{{.Status}}\t{{.Image}}\tvscode-{{.Label \"vsch.quality\"}}\t{{.Label \"vsch.local.folder\"}}"

選項 4：使用 Docker Compose

開啟本機終端機/命令提示字元（或在 VS Code 中使用本機視窗）。
前往包含您的 docker-compose.yml 檔案的目錄。
輸入 docker-compose down 來停止並刪除容器。如果您有多個 Docker Compose 檔案，可以使用 -f 引數指定額外的 Docker Compose 檔案。

選項 5：刪除所有未執行中的容器與映像檔

開啟本機終端機/命令提示字元（或在 VS Code 中使用本機視窗）。
輸入 docker system prune --all。

解決 Debian 8 映像檔的 Dockerfile 建置失敗問題

建置使用 Debian 8/Jessie 作為基底的映像檔（例如舊版的 node:8 映像檔）時，您可能會遇到下列錯誤

...
W: Failed to fetch http://deb.debian.org/debian/dists/jessie-updates/InRelease  Unable to find expected entry 'main/binary-amd64/Packages' in Release file (Wrong sources.list entry or malformed file)
E: Some index files failed to download. They have been ignored, or old ones used instead.
...

這是一個眾所周知的問題，原因是 Debian 8 已被「封存」。較新的映像檔版本通常會解決此問題，通常是升級至 Debian 9/Stretch。

有兩種方法可以解決此錯誤

選項 1：移除任何依賴該映像檔的容器，移除該映像檔，然後嘗試重新建置。這應該會下載一個不受此問題影響的已更新映像檔。詳情請參閱清理未使用的容器與映像檔。

選項 2：如果您不想刪除您的容器或映像檔，請在任何 apt 或 apt-get 指令之前，將這行加入您的 Dockerfile。它會為 Jessie 新增必要的來源清單

# Add archived sources to source list if base image uses Debian 8 / Jessie
RUN cat /etc/*-release | grep -q jessie && printf "deb http://archive.debian.org/debian/ jessie main\ndeb-src http://archive.debian.org/debian/ jessie main\ndeb http://security.debian.org jessie/updates main\ndeb-src http://security.debian.org jessie/updates main" > /etc/apt/sources.list

Docker CLI 僅支援使用您的 Docker ID，因此使用電子郵件登入可能會導致問題。詳情請參閱 Docker 問題 #935。

作為替代方案，請使用您的 Docker ID 而非電子郵件登入 Docker。

macOS 上 Hyperkit 的高 CPU 使用率

有一個關於 Docker for Mac 的已知問題，可能會導致 CPU 出現高峰。特別是在觀察檔案與進行建置時，高 CPU 使用率會隨之發生。如果您在活動監視器中看到 com.docker.hyperkit 的 CPU 使用率很高，而您的開發容器中幾乎沒有什麼活動，您很可能遇到了這個問題。請關注此 Docker 問題以取得更新與修復。

使用 SSH 通道連線至遠端 Docker 主機

在遠端 Docker Machine 或 SSH 主機上的容器內開發文章介紹了在處理遠端 Docker 主機時如何設定 VS Code。這通常只需設定 Container Tools 擴充功能的 containers.environment 屬性（於 settings.json 中）或將 DOCKER_HOST 環境變數設為 ssh:// 或 tcp:// URI 即可。

然而，由於 SSH 設定的複雜性或其他限制，您可能會在您的環境中遇到此方法無效的情況。在這種情況下，可以使用 SSH 通道作為備援。

使用 SSH 通道作為備援選項

您可以設定 SSH 通道，並將 Docker 通訊端從遠端主機轉發至您的本機。

遵循以下步驟

安裝 OpenSSH 相容的 SSH 客戶端。
依照下列方式更新您使用者或工作區 settings.json 中的 Container Tools 擴充功能 containers.environment 屬性
```
"containers.environment": {
    "DOCKER_HOST": "tcp://:23750"
}
```
從本機終端機 / PowerShell 執行下列指令（將 user@hostname 取代為您伺服器的遠端使用者與主機名稱 / IP）
```
ssh -NL localhost:23750:/var/run/docker.sock user@hostname
```

VS Code 現在將能夠附加至遠端主機上的任何執行中容器。您也可以使用專業的本機 devcontainer.json 檔案來建立/連線至遠端開發容器。

完成後，在終端機 / PowerShell 中按下 Ctrl+C 以關閉通道。

注意： 如果 ssh 指令失敗，您可能需要在 SSH 主機上 AllowStreamLocalForwarding。

在 SSH 主機（非本機）上，使用編輯器（如 Vim、nano 或 Pico）開啟 /etc/ssh/sshd_config。
新增設定 AllowStreamLocalForwarding yes。
重新啟動 SSH 伺服器（在 Ubuntu 上，請執行 sudo systemctl restart sshd）。
重試。

保留使用者設定檔

您可以使用 mounts 屬性在開發容器中保留使用者設定檔（例如保留 shell 歷史記錄），以便在重建容器後仍能使用。

    "mounts": [
        "source=profile,target=/root,type=volume",
        "target=/root/.vscode-server,type=volume"
    ],

上述程式碼首先建立一個名為 profile 的具名磁碟區並掛載至 /root，這將在重建後保留下來。接著，它會建立一個匿名磁碟區掛載至 /root/.vscode-server，該磁碟區會在重建時銷毀，這允許 VS Code 重新安裝擴充功能與點檔案 (dotfiles)。

進階容器設定技巧

請參閱進階容器設定文章，了解下列主題的相關資訊

新增環境變數

新增另一個本機檔案掛載

變更或移除預設原始程式碼掛載

提升容器磁碟效能

將非 root 使用者加入您的開發容器

設定 Docker Compose 的專案名稱

從容器內使用 Docker 或 Kubernetes

同時連線至多個容器

在遠端 Docker Machine 或 SSH 主機上的容器內開發

減少 Dockerfile 建置警告

與您的容器共用 git 憑證

擴充功能技巧

雖然許多擴充功能無需修改即可運作，但仍有一些問題可能會阻礙特定功能的預期運作。在某些情況下，您可以使用其他指令來繞過問題，而在其他情況下，擴充功能可能需要進行修改。遠端擴充功能技巧章節提供了常見問題與解決技巧的快速參考。您也可以參考關於支援遠端開發的主要擴充功能文章，以取得關於修改擴充功能以支援遠端擴充功能主機的深入指南。

問題與回饋

回報問題

如果您在使用 Dev Containers 擴充功能時遇到問題，請務必收集正確的記錄檔，以便我們協助診斷您的問題。您可以使用 Dev Containers: 顯示容器記錄 (Dev Containers: Show Container Log) 取得 Dev Containers 擴充功能的記錄檔。

如果您在遠端使用其他擴充功能時遇到問題（例如，其他擴充功能在遠端環境中無法正常載入或安裝），從 遠端擴充功能主機 (Remote Extension Host) 輸出頻道 (輸出：專注於輸出檢視) 取得記錄檔將會很有幫助，請在下拉式選單中選擇 記錄 (遠端擴充功能主機) (Log (Remote Extension Host))。

注意：如果您只看到 記錄 (擴充功能主機) (Log (Extension Host))，這代表是本機擴充功能主機，而遠端擴充功能主機尚未啟動。這是因為記錄頻道僅在記錄檔案建立後才會產生，因此如果遠端擴充功能主機未啟動，遠端擴充功能主機記錄檔案就不會建立，也不會顯示在輸出檢視中。將此資訊包含在您的問題報告中仍然是有幫助的。