🚀 在 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 應用程式的引數。 取決於平台。預設的 scaffolding 顯示於 上方
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} 命令的字串傳回值。