自定义 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是dockerBuild和platform：

• 该dockerBuild对象指定 Docker 构建命令的参数。该对象指定的值直接应用于 Docker 构建 CLI 调用。
• 该platform属性是一个提示，可更改docker-build任务确定 Docker 构建默认值的方式。

有关所有任务属性的完整列表，请参阅属性参考。

平台支持

虽然docker-build中的任务tasks.json可用于构建任何 Docker 映像，但该扩展对 Node.js、Python 和 .NET Core 具有显式支持（并简化了配置）。

Node.js（docker 构建）

使用默认值的最小配置

基于 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	该文件Dockerfile与所在目录位于同一目录中package.json。
dockerBuild.tag	应用程序的name属性package.json（如果已定义），否则为所在文件夹的基本名称package.json。

Python（docker 构建）

使用默认值的最小配置

基于 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 构建）

使用默认值的最小配置

当您构建基于 .NET 的 Docker 映像时，您可以省略该platform属性并仅设置netCore对象（当对象存在时platform隐式设置）。请注意，这是必需的属性：netcorenetCoreappProject

{
  "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	任务中没有 Python 的对象属性docker-build。
netCore	确定特定于 .NET 项目的选项（见下文）。

dockerBuild 对象属性

财产	描述	docker buildCLI 等效项
context	Docker 构建上下文的路径。 必需的，除非从平台推断。	PATH
dockerfile	Dockerfile 的路径。 必需的，除非从平台推断。	-f或者--file
tag	应用于 Docker 映像的标签。 必需的，除非从平台推断。	-t或者--tag
buildArgs	构建应用于命令行的参数。这是键值对的列表。	--build-arg
labels	添加到 Docker 镜像的标签。这是键值对（JSON 对象）的列表。 除了此处指定的标签之外，还会将一个com.microsoft.created-by设置为 的标签visual-studio-code添加到图像中。includeDefaults可以通过将对象的属性设置为 false 来关闭此行为labels。	--label
target	Dockerfile 中要构建的目标。	--target
pull	是否在构建之前拉取新的基础镜像。	--pull
customOptions	在上下文参数之前添加的任何额外参数。不会尝试解决与其他选项的冲突或验证此选项。	（任何）

节点对象属性（docker-build任务）

财产	描述	默认
package	package.json与 Dockerfile 和任务关联的文件的路径docker-build。	package.json根工作区文件夹中的文件。

netCore 对象属性（docker-build任务）

财产	描述
appProject	与 Dockerfile 和任务关联的.NET 项目文件（.csproj、等） 。始终需要。.fsprojdocker-build

Docker 运行任务

该docker-run任务tasks.json使用 Docker 命令行 (CLI) 创建并启动 Docker 容器。该任务可以单独使用，也可以作为任务链的一部分来调试 Docker 容器中的应用程序。

该任务最重要的配置设置docker-run是dockerRun和platform：

• 该dockerRun对象指定 Docker 运行命令的参数。此对象指定的值直接应用于 Docker 运行 CLI 调用。
• 该platform属性是一个提示，用于更改docker-run任务确定 Docker 运行默认值的方式。

有关所有任务属性的完整列表，请参阅属性参考。

Docker运行平台支持

虽然该docker-run任务可用于运行任何 Docker 映像，但该扩展明确支持 Node.js、Python 和 .NET（并简化了配置）。

Node.js（docker 运行）

使用默认值的最小配置

基于 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	从 中的 npmstart脚本生成package.json（如果存在），否则main从package.json.
dockerRun.containerName	源自应用程序包名称。
dockerRun.image	来自从属docker-build任务（如果存在）或派生自应用程序包名称的标记，其本身派生自其所在文件夹name内的属性或基本名称。package.json

Python（docker 运行）

当构建基于Python的Docker镜像时，您可以省略该platform属性并仅设置python对象（当对象存在时platform隐式设置）pythonpython

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 运行）

使用默认值的最小配置

构建基于 .NET 的 Docker 映像时，您可以省略该platform属性并仅设置netCore对象（当对象存在时platform隐式设置）。请注意，这是必需的属性：netcorenetCoreappProject

{
  "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_ENVIRONMENT、ASPNETCORE_URLS和DOTNET_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	在图像参数之前添加的任何额外参数。不会尝试解决与其他选项的冲突或验证此选项。	（任何）

端口对象属性

财产	描述	默认
containerPort	容器上绑定的端口号。 必需的。
hostPort	主机上绑定的端口号。	（由 Docker 随机选择）
protocol	绑定协议（tcp或udp）。	tcp

extraHosts 对象属性

财产	描述
hostname	DNS 解析的主机名。 必需的。
ip	与上述主机名关联的 IP 地址。 必需的。

卷对象属性

财产	描述	默认
localPath	将映射的本地计算机上的路径。 必需的。
containerPath	本地路径将映射到的容器中的路径。 必需的。
permissions	容器对映射路径具有的权限。可以是ro（只读）或rw（读写）。	依赖于容器。

节点对象属性（docker-run任务）

财产	描述	默认
package	package.json与任务关联的文件的路径docker-run。	package.json根工作区文件夹中的文件。
enableDebugging	是否在容器内启用调试。	false
inspectMode	default定义应用程序和调试器（或）之间的初始交互break。 该值default允许应用程序运行，直到附加调试器。 该值break会阻止应用程序运行，直到调试器附加为止。	default
inspectPort	应进行调试的端口。	9229

python 对象属性（docker-run任务）

财产	描述	默认
args	传递给 Python 应用程序的参数。	平台相关。上面显示的脚手架的默认值
debugPort	调试器将侦听的端口。	5678
wait	是否等待调试器连接。	true
module	要运行的 Python 模块（仅应选择模块或文件）。
file	要运行的 Python 文件（仅应选择模块或文件）。

netCore 对象属性（docker-run任务）

财产	描述
appProject	与任务关联的.NET 项目文件（.csproj、.fsproj等）docker-run。 必需的。
configureSsl	是否配置 ASP.NET Core SSL 证书和其他设置以在容器中的服务上启用 SSL。
enableDebugging	是否启用启动的容器进行调试。这将推断出额外的卷映射和调试所需的其他选项。

Docker 撰写任务

该docker-compose任务tasks.json使用 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"
        ]
      }
    }
  ]
}

撰写任务参考

以下是可用于配置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 YAML 文件的列表docker-compose。如果未指定，Docker Compose CLI 会查找docker-compose.yml和docker-compose.override.yml。	-f <file>
envFile	读入并应用于容器的环境变量文件。	--env-file <file>
projectName	命名和标记 Docker 对象时使用的备用项目名称。如果在编写时使用备用项目名称，则在编写时必须指定相同的项目名称。	--project-name <name>

向上对象属性

财产	描述	CLI 等效项	默认
detached	是否分离运行。	-d	true
build	是否在运行前构建。	--build	true
scale	要运行的每个服务的实例数。这是键值对的列表。	--scale SERVICE=NUM
services	要启动的服务的子集。不能与 结合使用profiles。	[SERVICE...]	（全部）
profiles	要启动的配置文件的子集。不能与 结合使用services。	--profile <profile>	（全部）
customOptions	在参数后面添加的任何额外参数up。不会尝试解决与其他选项的冲突或验证此选项。	（任何）

向下对象属性

财产	描述	CLI 等效项	默认
removeImages	是否删除图像以及删除哪些图像。all将删除任何服务使用的所有图像，local将仅删除没有自定义标签的图像。不设置此项将不会删除任何图像。	--rmi
removeVolumes	是否删除命名卷。	-v	false
customOptions	在参数后面添加的任何额外参数down。不会尝试解决与其他选项的冲突或验证此选项。	（任何）

命令定制

当您执行各种操作（例如构建映像、运行容器、附加到容器和查看容器日志）时，Docker 扩展会执行许多 Docker CLI 命令。其中一些命令具有大量可选参数，通常在非常特定的场景中使用。作为上述 Visual Studio Code 任务的替代方案，可以在不使用任务时自定义多个命令。

例如， Compose Up命令中的标记${serviceList}和允许轻松启动 Docker Compose YAML 文件中的服务子集。${profileList}

对于每个可自定义的 Docker 命令，都可以使用配置设置来设置要执行的内容的模板。或者，您可以定义多个模板，可选地使用正则表达式，匹配时，提示应使用模板的上下文。模板支持一些类似于launch.json和 的标记tasks.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. 检查受约束的模板。受约束的模板具有match. 将正则表达式match与上下文提示进行比较，例如图像名称、容器名称等。
   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.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 组合

配置设置	默认值
docker.commands.composeUp	${composeCommand} ${configurationFile} up ${detached} ${build}

支持的代币：

代币	描述
${configurationFile}	设置为-f加上所选 Docker Compose YAML 文件的工作区相对路径。
${detached}	-d如果配置设置docker.dockerComposeDetached设置为 ，则设置为true。否则，设置为""。
${build}	--build如果配置设置docker.dockerComposeBuild设置为 ，则设置为true。否则，设置为""。
${serviceList}	如果指定，则在运行命令时提示启动服务的子集。
${profileList}	如果指定并且 Docker Compose YAML 文件包含配置文件，则在运行命令时提示启动配置文件的子集。
${composeCommand}	如果设置，则设置为设置的值docker.composeCommand，否则扩展将尝试自动确定要使用的命令（docker compose或docker-compose）。

Docker 撰写下来

配置设置	默认值
docker.commands.composeDown	${composeCommand} ${configurationFile} down

支持的代币：

代币	描述
${configurationFile}	设置为-f加上所选 Docker Compose YAML 文件的工作区相对路径。
${composeCommand}	如果设置，则设置为设置的值docker.composeCommand，否则扩展将尝试自动确定要使用的命令（docker compose或docker-compose）。

其他支持的令牌

除了特定于命令的受支持标记之外，所有命令模板还支持以下标记：

代币	描述
${workspaceFolder}	选定的工作区文件夹路径。
${config:some.setting.identifier}	任何配置设置的值，只要它是字符串、数字或布尔值。这些设置标识符可以任意定义，不需要属于 Visual Studio Code 或任何扩展。
${env:Name}	环境变量的值。
${command:commandID}	命令的字符串返回值。