🚀 在 VS Code 中免費取得

自訂 Docker 擴充功能

Docker 擴充功能包含數個 Visual Studio Code 工作,可用於控制 Docker 建置執行的行為,並構成偵錯時容器啟動的基礎。

這些工作可進行大量的控制和自訂。最終組態是通用預設值、平台特定預設值 (例如 Node.js、Python 或 .NET) 和使用者輸入的組合。當使用者輸入與預設值衝突時,使用者輸入優先。

Docker 擴充功能工作支援 Visual Studio Code 工作的所有常見功能 (例如,將工作分組為複合工作)。如需常見工作功能和屬性的詳細資訊,請參閱 Visual Studio Code 自訂工作文件。

Docker 建置工作

docker-build 工作會使用 Docker 命令列 (CLI) 建置 Docker 映像。此工作可以單獨使用,也可以作為工作鏈的一部分使用,以在 Docker 容器中執行和/或偵錯應用程式。

docker-build 工作最重要的組態設定是 dockerBuildplatform

  • dockerBuild 物件指定 Docker 建置命令的參數。此物件指定的值會直接套用至 Docker 建置 CLI 調用。
  • platform 屬性是一個提示,可變更 docker-build 工作判斷 Docker 建置預設值的方式。

如需所有工作屬性的完整清單,請參閱屬性參考

平台支援

雖然 tasks.json 中的 docker-build 工作可用於建置任何 Docker 映像,但此擴充功能對 Node.js、Python 和 .NET Core 具有明確的支援 (和簡化的組態)。

Node.js (docker-build)

使用預設值的最小組態

沒有特定平台選項的 Node.js 型 Docker 映像可以僅將 platform 屬性設定為 node

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build Node Image",
      "type": "docker-build",
      "platform": "node"
    }
  ]
}

平台預設值

對於 Node.js Docker 映像,docker-build 工作會推斷下列選項

屬性 推斷值
dockerBuild.context package.json 位於相同目錄中的目錄。
dockerBuild.dockerfile package.json 位於相同目錄中的檔案 Dockerfile
dockerBuild.tag 應用程式 package.json 中的 name 屬性 (如果已定義),否則為 package.json 所在資料夾的基底名稱。

Python (docker-build)

使用預設值的最小組態

沒有特定平台選項的 Python 型 Docker 映像可以僅將 platform 屬性設定為 python

{
  "tasks": [
    {
      "type": "docker-build",
      "label": "docker-build",
      "platform": "python"
    }
  ]
}

平台預設值

對於 Python Docker 映像,docker-build 工作會推斷下列選項

屬性 推斷值
dockerBuild.context 預設內容是工作區資料夾。
dockerBuild.dockerfile 預設 Dockerfile 路徑將位於工作區資料夾的根目錄中。
dockerBuild.tag 根工作區資料夾的基底名稱。
dockerBuild.pull 預設為 true,以便在建置前提取新的基底映像。

.NET (docker-build)

使用預設值的最小組態

當您建置 .NET 型 Docker 映像時,您可以省略 platform 屬性,而僅設定 netCore 物件 (當 netCore 物件存在時,platform 會隱含地設定為 netcore)。請注意,appProject 是必要屬性

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build Node Image",
      "type": "docker-build",
      "netCore": {
        "appProject": "${workspaceFolder}/project.csproj"
      }
    }
  ]
}

平台預設值

對於 .NET 型映像,docker-build 工作會推斷下列選項

屬性 推斷值
dockerBuild.context 根工作區資料夾。
dockerBuild.dockerfile 根工作區資料夾中的檔案 Dockerfile
dockerBuild.tag 根工作區資料夾的基底名稱。

建置工作參考

以下是可用於設定 docker-build 工作的所有屬性。除非另有說明,否則所有屬性都是選用的。

屬性 描述
dockerBuild 用於控制執行的 docker build 命令的選項 (請參閱下方)。
除非設定 platform,否則為必要項。
platform 判斷平台:.NET (netcore) 或 Node.js (node) 和 docker build 命令的預設設定。
node 判斷 Node.js 專案的特定選項 (請參閱下方)。
python docker-build 工作中沒有 Python 的物件屬性。
netCore 判斷 .NET 專案的特定選項 (請參閱下方)。

dockerBuild 物件屬性

屬性 描述 docker build CLI 對等項目
context Docker 建置內容的路徑。
必要,除非從平台推斷。
PATH
dockerfile Dockerfile 的路徑。
必要,除非從平台推斷。
-f--file
tag 套用至 Docker 映像的標籤。
必要,除非從平台推斷。
-t--tag
buildArgs 套用至命令列的建置引數。這是索引鍵值組的清單。 --build-arg
labels 新增至 Docker 映像的標籤。這是索引鍵值組 (JSON 物件) 的清單。
除了此處指定的標籤外,還會將標籤 com.microsoft.created-by (設定為 visual-studio-code) 新增至映像。可以將 labels 物件的 includeDefaults 屬性設定為 false 來關閉此行為。
--label
target Dockerfile 中要建置到的目標。 --target
pull 在建置前是否提取新的基底映像。 --pull
customOptions 在內容引數之前新增的任何額外參數。不會嘗試解決與其他選項的衝突或驗證此選項。 (任何)

node 物件屬性 (docker-build 工作)

屬性 描述 預設值
package 與 Dockerfile 和 docker-build 工作相關聯的 package.json 檔案的路徑。 根工作區資料夾中的檔案 package.json

netCore 物件屬性 (docker-build 工作)

屬性 描述
appProject 與 Dockerfile 和 docker-build 工作相關聯的 .NET 專案檔案 (.csproj.fsproj 等)。
一律為必要項。

Docker 執行工作

tasks.json 中的 docker-run 工作會使用 Docker 命令列 (CLI) 建立並啟動 Docker 容器。此工作可以單獨使用,也可以作為工作鏈的一部分使用,以在 Docker 容器中偵錯應用程式。

docker-run 工作最重要的組態設定是 dockerRunplatform

  • dockerRun 物件指定 Docker 執行命令的參數。此物件指定的值會直接套用至 Docker 執行 CLI 調用。
  • platform 屬性是一個提示,可變更 docker-run 工作判斷 Docker 執行預設值的方式。

如需所有工作屬性的完整清單,請參閱屬性參考

Docker 執行平台支援

雖然 docker-run 工作可用於執行任何 Docker 映像,但此擴充功能對 Node.js、Python 和 .NET 具有明確的支援 (和簡化的組態)。

Node.js (docker-run)

使用預設值的最小組態

沒有特定平台選項的 Node.js 型 Docker 映像可以僅將 platform 屬性設定為 node

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run Node Image",
      "node": "docker-run",
      "platform": "node"
    }
  ]
}

平台預設值

對於 Node.js 型 Docker 映像,docker-run 工作會推斷下列選項

屬性 推斷值
dockerRun.command package.json 中的 npm start 指令碼產生 (如果存在),否則從 package.json 中的 main 屬性產生。
dockerRun.containerName 衍生自應用程式套件名稱。
dockerRun.image 來自相依 docker-build 工作的標籤 (如果存在) 或衍生自應用程式套件名稱,應用程式套件名稱本身衍生自 package.json 中的 name 屬性或其所在資料夾的基底名稱。

Python (docker-run)

建置 Python 型 Docker 映像時,您可以省略 platform 屬性,而僅設定 python 物件 (當 python 物件存在時,platform 會隱含地設定為 python)

Django 應用程式的最小組態

{
  "type": "docker-run",
  "label": "docker-run: debug",
  "dependsOn": ["docker-build"],
  "python": {
    "args": ["runserver", "0.0.0.0:8000", "--nothreading", "--noreload"],
    "file": "path_to/manage.py"
  }
}

Flask 應用程式的最小組態

{
  "type": "docker-run",
  "label": "docker-run: debug",
  "dependsOn": ["docker-build"],
  "dockerRun": {
    "env": {
      "FLASK_APP": "path_to/flask_entry_point.py"
    }
  },
  "python": {
    "args": ["run", "--no-debugger", "--no-reload", "--host", "0.0.0.0", "--port", "5000"],
    "module": "flask"
  }
}

一般應用程式的最小組態

{
  "type": "docker-run",
  "label": "docker-run: debug",
  "dependsOn": ["docker-build"],
  "python": {
    "file": "path_to/app_entry_point.py"
  }
}

平台預設值

對於 Python 型 Docker 映像,docker-run 工作會推斷下列選項

屬性 推斷值
dockerRun.command 由 Python 物件產生,並由 Python 偵錯工具呼叫。
dockerRun.containerName 衍生自根工作區資料夾的基底名稱。
dockerRun.image 來自相依 docker-build 工作的標籤 (如果存在) 或衍生自根工作區資料夾的基底名稱。

.NET (docker-run)

使用預設值的最小組態

建置 .NET 型 Docker 映像時,您可以省略 platform 屬性,而僅設定 netCore 物件 (當 netCore 物件存在時,platform 會隱含地設定為 netcore)。請注意,appProject 是必要屬性

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run .NET Core Image",
      "type": "docker-run",
      "netCore": {
        "appProject": "${workspaceFolder}/project.csproj"
      }
    }
  ]
}

平台預設值

對於 .NET 型映像,docker-run 工作會推斷下列選項

屬性 推斷值
dockerRun.containerName 衍生自根工作區資料夾的基底名稱。
dockerRun.env 新增下列必要的環境變數:ASPNETCORE_ENVIRONMENTASPNETCORE_URLSDOTNET_USE_POLLING_FILE_WATCHER
dockerRun.image 來自相依 docker-build 工作的標籤 (如果存在) 或衍生自根工作區資料夾的基底名稱。
dockerRun.os Linux
dockerRun.volumes 新增下列必要的磁碟區:本機應用程式資料夾、原始檔資料夾、偵錯工具資料夾、NuGet 套件資料夾和 NuGet 回退資料夾。

執行工作參考

以下是可用於設定 docker-run 工作的所有屬性。除非另有說明,否則所有屬性都是選用的。

屬性 描述
dockerRun 用於控制執行的 docker run 命令的選項 (請參閱下方)。
除非設定 platform,否則為必要項。
platform 判斷平台:.NET (netcore) 或 Node.js (node) 和 docker run 命令的預設設定。
node 對於 Node.js 專案,這會控制各種選項 (請參閱下方)。
python 對於 Python 專案,這會控制各種選項 (請參閱下方)。
netCore 對於 .NET 專案,這會控制各種選項 (請參閱下方)。

dockerRun 物件屬性

屬性 描述 CLI 對等項目
image 要執行的映像名稱 (標籤)。
必要,除非從平台推斷。
IMAGE
command 在啟動容器時要執行的命令。
必要,除非從平台推斷。
COMMAND [ARG...]
containerName 給予已啟動容器的名稱。
必要,除非從平台推斷。
--name
env 在容器中設定的環境變數。這是索引鍵值組的清單。 -e--env
envFiles 這是 .env 檔案的清單。 --env-file
labels 給予已啟動容器的標籤。這是索引鍵值組的清單。 --label
network 容器將連線到的網路名稱。 --network
networkAlias 已啟動容器的網路範圍別名。 --network-alias
os 預設值為 Linux,另一個選項為 Windows。使用的容器作業系統。 不適用
ports 要從容器發佈 (對應) 至主機的連接埠。這是物件的清單 (請參閱下方)。 -p--publish
portsPublishAll 是否發佈 Docker 映像公開的所有連接埠。如果未明確發佈任何連接埠,則預設為 true -P
extraHosts 要新增至容器以進行 DNS 網域名稱解析的主機。這是物件的清單 (請參閱下方)。 --add-host
volumes 要對應至已啟動容器的磁碟區。這是物件的清單 (請參閱下方)。 -v--volume
remove 是否在容器停止後移除容器。 --rm
customOptions 在映像引數之前新增的任何額外參數。不會嘗試解決與其他選項的衝突或驗證此選項。 (任何)

ports 物件屬性

屬性 描述 預設值
containerPort 在容器上繫結的連接埠號碼。
必要項。
hostPort 在主機上繫結的連接埠號碼。 (由 Docker 隨機選取)
protocol 繫結的通訊協定 (tcpudp)。 tcp

extraHosts 物件屬性

屬性 描述
hostname 用於 DNS 網域名稱解析的主機名稱。
必要項。
ip 與上述主機名稱相關聯的 IP 位址。
必要項。

volumes 物件屬性

屬性 描述 預設值
localPath 將對應的本機電腦上的路徑。
必要項。
containerPath 容器中將對應本機路徑的路徑。
必要項。
permissions 容器在對應路徑上擁有的權限。可以是 ro (唯讀) 或 rw (讀寫)。 容器相依。

node 物件屬性 (docker-run 工作)

屬性 描述 預設值
package docker-run 工作相關聯的 package.json 檔案的路徑。 根工作區資料夾中的檔案 package.json
enableDebugging 是否在容器中啟用偵錯。 false
inspectMode 定義應用程式與偵錯工具之間的初始互動 (defaultbreak)。
default 允許應用程式執行,直到偵錯工具附加。
break 防止應用程式執行,直到偵錯工具附加。
default
inspectPort 應進行偵錯的連接埠。 9229

python 物件屬性 (docker-run 工作)

屬性 描述 預設值
args 傳遞至 Python 應用程式的引數。 平台相依。上方顯示的 Scaffold 預設值
debugPort 偵錯工具將接聽的連接埠。 5678
wait 是否等候偵錯工具附加。 true
module 要執行的 Python 模組 (應僅選擇模組檔案)。
file 要執行的 Python 檔案 (應僅選擇模組檔案)。

netCore 物件屬性 (docker-run 工作)

屬性 描述
appProject docker-run 工作相關聯的 .NET 專案檔案 (.csproj.fsproj 等)。
必要項。
configureSsl 是否設定 ASP.NET Core SSL 憑證和其他設定,以在容器中的服務上啟用 SSL。
enableDebugging 是否啟用已啟動的容器以進行偵錯。這會推斷偵錯所需的其他磁碟區對應和其他選項。

Docker Compose 工作

tasks.json 中的 docker-compose 工作會使用 Docker Compose 命令列 (CLI) 建立並啟動 Docker 容器。此工作可以單獨使用,也可以作為工作鏈的一部分使用,以在 Docker 容器中偵錯應用程式。

docker-compose 工作最重要的組態設定是 dockerCompose

  • dockerCompose 物件指定 Docker Compose 命令的參數。此物件指定的值會直接套用至 Docker Compose CLI 調用。

如需所有工作屬性的完整清單,請參閱屬性參考

組態範例

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run docker-compose up",
      "type": "docker-compose",
      "dockerCompose": {
        "up": {
          "detached": true,
          "build": true,
          "services": ["myservice"]
        },
        "files": [
          "${workspaceFolder}/docker-compose.yml",
          "${workspaceFolder}/docker-compose.debug.yml"
        ]
      }
    }
  ]
}

Compose 工作參考

以下是可用於設定 docker-compose 工作的所有屬性。除非另有說明,否則所有屬性都是選用的。

屬性 描述
dockerCompose 用於控制執行的 docker-compose 命令的選項 (請參閱下方)。
必要項。

dockerCompose 物件屬性

屬性 描述 CLI 對等項目
up 執行 docker-compose up 命令。
必須指定此項或 down,但不能同時指定兩者。
docker-compose up
down 執行 docker-compose down 命令。
必須指定此項或 up,但不能同時指定兩者。
docker-compose down
files 要在 docker-compose 命令中使用的 Docker Compose YAML 檔案清單。如果未指定,Docker Compose CLI 會尋找 docker-compose.ymldocker-compose.override.yml -f <file>
envFile 讀取並套用至容器的環境變數檔案。 --env-file <file>
projectName 在命名和標記 Docker 物件時要使用的替代專案名稱。如果在使用替代專案名稱撰寫 up 時,則在撰寫 down 時必須指定相同的專案名稱。 --project-name <name>

up 物件屬性

屬性 描述 CLI 對等項目 預設值
detached 是否以分離模式執行。 -d true
build 是否在執行前建置。 --build true
scale 要執行的每個服務執行個體數目。這是索引鍵值組的清單。 --scale SERVICE=NUM
services 要啟動的服務子集。無法與 profiles 結合使用。 [SERVICE...] (全部)
profiles 要啟動的設定檔子集。無法與 services 結合使用。 --profile <profile> (全部)
customOptions 要在 up 引數之後新增的任何額外參數。不會嘗試解決與其他選項的衝突或驗證此選項。 (任何)

down 物件屬性

屬性 描述 CLI 對等項目 預設值
removeImages 是否移除映像,以及移除哪些映像。all 將移除任何服務使用的所有映像,local 將僅移除沒有自訂標籤的映像。將此項保留為未設定將不會移除任何映像。 --rmi
removeVolumes 是否移除具名磁碟區。 -v false
customOptions 要在 down 引數之後新增的任何額外參數。不會嘗試解決與其他選項的衝突或驗證此選項。 (任何)

命令自訂

當您執行各種作業時,例如建置映像、執行容器、附加至容器和檢視容器記錄,Docker 擴充功能會執行許多 Docker CLI 命令。其中一些命令有大量選用引數,通常用於非常特定的案例中。作為上述 Visual Studio Code 工作的替代方案,當未使用工作時,可以自訂數個命令。

例如,Compose Up 命令中的權杖 ${serviceList}${profileList} 可讓您輕鬆啟動 Docker Compose YAML 檔案中服務的子集。

對於每個可自訂的 Docker 命令,組態設定可用於設定要執行的範本。或者,您可以定義多個範本,選擇性地使用規則運算式,當規則運算式符合時,會提示範本應該使用的內容。範本支援一些類似於 launch.jsontasks.json 的權杖,例如 ${workspaceFolder}

設定 JSON 結構描述

您有兩個選項可以設定每個範本 (如下所列)。第一個選項是覆寫預設行為的單一範本

{
  "docker.commands.build": "docker build --rm -f \"${dockerfile}\" -t ${tag} \"${context}\""
}

第二個選項是多個範本,將根據 match 規則運算式以及使用者輸入來選擇範本。

例如,下列範例中顯示了三個範本

{
  "docker.commands.build": [
    {
      "label": "Default build command",
      "template": "docker build --rm -f \"${dockerfile}\" -t ${tag} \"${context}\""
    },
    {
      "label": "Alpine-specific build command",
      "template": "docker build -p 1234:1234 -f \"${dockerfile}\" -t ${tag} \"${context}\"",
      "match": "alpine"
    }
  ]
}

選取行為

選擇要執行的命令範本是根據下列規則選取的

  1. 如果未設定任何設定,則會選擇預設命令範本。
  2. 如果僅設定單一範本 (上述第一個範例),則會選擇該範本。
  3. 如果設定了多個範本
    1. 會檢查受限制的範本。受限制的範本具有 matchmatch 規則運算式會與內容提示 (例如,映像名稱、容器名稱等) 進行比較。
    2. 如果多個受限制的範本適用,系統會提示使用者選擇。如果僅適用一個範本,則不會提示使用者。
    3. 如果沒有適用的受限制範本,則會檢查不受限制的範本。不受限制的範本沒有 match,因此一律適用。
    4. 如果多個不受限制的範本適用,系統會提示使用者選擇。如果僅適用一個範本,則不會提示使用者。

Docker 建置

組態設定 預設值
docker.commands.build ${containerCommand} build --rm -f "${dockerfile}" -t ${tag} "${context}"

支援的權杖

權杖 描述
${containerCommand} 用於執行容器命令的 CLI 命令/可執行檔。
${dockerfile} 所選 Dockerfile 的工作區相對路徑。
${tag} 使用者在叫用建置命令時輸入/確認的值。如果先前已建置,則預設為先前針對該 Dockerfile 輸入的值。
${context} 如果已設定,則為 docker.imageBuildContextPath 組態設定的值。否則,為 Dockerfile 所在的工作區相對資料夾。

注意:如果 docker.commands.build 設定不包含 ${tag} 權杖,則系統不會提示使用者輸入/確認標籤。

注意match 規則運算式將與選取的 Dockerfile 名稱和工作區資料夾名稱進行比較。

Docker 執行

組態設定 預設值
docker.commands.run ${containerCommand} run --rm -d ${exposedPorts} ${tag}
docker.commands.runInteractive ${containerCommand} run --rm -it ${exposedPorts} ${tag}

支援的權杖

權杖 描述
${containerCommand} 用於執行容器命令的 CLI 命令/可執行檔。
${exposedPorts} 從映像中公開的連接埠清單產生 (最終來自 Dockerfile),其中每個公開的連接埠都會對應到本機電腦上的相同連接埠。例如,"EXPOSE 5000 5001" 將產生 "-p 5000:5000 -p 5001:5001"
${tag} 所選映像的完整標籤。

注意match 規則運算式將與所選映像的完整標籤進行比較。

Docker 附加

組態設定 預設值
docker.commands.attach ${containerCommand} exec -it ${containerId} ${shellCommand}

支援的權杖

權杖 描述
${containerCommand} 用於執行容器命令的 CLI 命令/可執行檔。
${containerId} 要附加的容器 ID。
${shellCommand} 如果容器中存在 bash,則會在此處取代,否則為 sh。在 Windows 容器中,一律使用 cmd

注意match 規則運算式將與容器名稱和容器映像的完整標籤進行比較。

Docker 記錄

組態設定 預設值
docker.commands.logs ${containerCommand} logs -f ${containerId}

支援的權杖

權杖 描述
${containerCommand} 用於執行容器命令的 CLI 命令/可執行檔。
${containerId} 要檢視記錄的容器 ID。

注意match 規則運算式將與容器名稱和容器映像的完整標籤進行比較。

Docker Compose Up

組態設定 預設值
docker.commands.composeUp ${composeCommand} ${configurationFile} up ${detached} ${build}

支援的權杖

權杖 描述
${configurationFile} 設定為 -f 加上所選 Docker Compose YAML 檔案的工作區相對路徑。
${detached} 如果組態設定 docker.dockerComposeDetached 設定為 true,則設定為 -d。否則,設定為 ""
${build} 如果組態設定 docker.dockerComposeBuild 設定為 true,則設定為 --build。否則,設定為 ""
${serviceList} 如果指定,則在執行命令時提示要啟動的服務子集。
${profileList} 如果指定且 Docker Compose YAML 檔案包含設定檔,則在執行命令時提示要啟動的設定檔子集。
${composeCommand} 如果已設定,則設定為 docker.composeCommand 設定的值,否則擴充功能會嘗試自動判斷要使用的命令 (docker composedocker-compose)。

Docker Compose Down

組態設定 預設值
docker.commands.composeDown ${composeCommand} ${configurationFile} down

支援的權杖

權杖 描述
${configurationFile} 設定為 -f 加上所選 Docker Compose YAML 檔案的工作區相對路徑。
${composeCommand} 如果已設定,則設定為 docker.composeCommand 設定的值,否則擴充功能會嘗試自動判斷要使用的命令 (docker composedocker-compose)。

其他支援的權杖

除了命令特定的支援權杖之外,所有命令範本中都支援下列權杖

權杖 描述
${workspaceFolder} 選取的工作區資料夾路徑。
${config:some.setting.identifier} 任何組態設定的值,只要它是字串、數字或布林值即可。這些設定識別碼可以任意定義,且不需要屬於 Visual Studio Code 或任何擴充功能。
${env:Name} 環境變數的值。
${command:commandID} 命令的字串傳回值。