在 Compose 文件中通过插值设置、使用和管理变量

Compose 文件可以使用变量以提供更高的灵活性。如果您想在多个版本之间快速切换镜像标签进行测试，或者希望将卷源调整为本地环境，则无需每次编辑 Compose 文件，只需设置变量，这些变量会在运行时将值插入到您的 Compose 文件中。

插值也可用于在运行时将值插入到您的 Compose 文件中，随后这些值会被用作变量传递到容器的环境中。

以下是一个简单的示例：

$ cat .env
TAG=v1.5
$ cat compose.yml
services:
  web:
    image: "webapp:${TAG}"

当您运行 docker compose up 时，Compose 文件中定义的 web 服务会 插值替换 镜像 webapp:v1.5，该镜像是在 .env 文件中设置的。您可以使用 config 命令 进行验证，该命令会将解析后的应用配置打印到终端：

$ docker compose config
services:
  web:
    image: 'webapp:v1.5'

插值语法

插值适用于未加引号和双引号的值。 支持带花括号（${VAR}）和不带花括号（$VAR）的表达式。

对于大括号表达式，支持以下格式：

• 直接替换
  • ${VAR} -> VAR 的值
• 默认值
  • ${VAR:-default} -> 如果 VAR 已设置且非空，则为其值，否则为 default
  • ${VAR-default} -> 如果 VAR 已设置，则为其值，否则为 default
• 必需的值
  • ${VAR:?error} -> 如果已设置且非空，则值为VAR，否则报错退出
  • ${VAR?error} -> 如果已设置，则值为VAR，否则报错退出
• 替代值
  • ${VAR:+replacement} -> 如果设置了 VAR 且非空，则为 replacement，否则为空
  • ${VAR+replacement} -> 如果设置了 VAR，则为 replacement，否则为空

更多信息，请参阅 插值在 Compose 规范中。

通过插值设置变量的方法

Docker Compose 可以从多个来源将变量插值到您的 Compose 文件中。

请注意，当同一变量由多个来源声明时，适用优先级规则：

1. 来自您的 Shell 环境的变量
2. 如果未设置 --env-file，则由本地工作目录 (PWD) 中的 .env 文件设置的变量
3. 由项目目录中的 --env-file 或 .env 文件设置的变量

您可以通过运行 docker compose config --environment 来检查 Compose 用于插值 Compose 模型的变量和值。

.env 个文件

Docker Compose 中的 .env 文件是一个文本文件，用于定义在运行 docker compose up 时应可供插值使用的变量。该文件通常包含变量的键值对，可让您在一个位置集中管理配置。如果您需要存储多个变量，.env 文件将非常有用。

.env 文件是设置变量的默认方法。.env 文件应放置在项目目录的根目录下，与您的 compose.yaml 文件相邻。有关环境变量文件格式的更多信息，请参阅 环境变量文件的语法。

基本示例：

$ cat .env
## define COMPOSE_DEBUG based on DEV_MODE, defaults to false
COMPOSE_DEBUG=${DEV_MODE:-false}

$ cat compose.yaml 
  services:
    webapp:
      image: my-webapp-image
      environment:
        - DEBUG=${COMPOSE_DEBUG}

$ DEV_MODE=true docker compose config
services:
  webapp:
    environment:
      DEBUG: "true"

附加信息

• 如果您在 .env 文件中定义了一个变量，则可以通过 environment 属性 在您的 compose.yml 中直接引用它。例如，如果您的 .env 文件包含环境变量 DEBUG=1，并且您的 compose.yml 文件如下所示：

   services:
     webapp:
       image: my-webapp-image
       environment:
         - DEBUG=${DEBUG}

  Docker Compose 将 ${DEBUG} 替换为 .env 文件中的值

  重要

  请注意，在 .env 文件中使用变量作为容器环境变量时，需留意 环境变量的优先级。

• 您可以将 .env 文件放置在项目目录根目录以外的位置，然后在 CLI 中使用--env-file 选项，以便 Compose 能够找到该文件。

• 您的 .env 文件可以被另一个 .env 覆盖，如果它被 用 --env-file 替换。

重要

来自 .env 个文件的替换是 Docker Compose CLI 的一项功能。

当运行 docker stack deploy 时，Swarm 不支持此操作。

.env 文件语法

以下语法规则适用于环境文件：

• 以 # 开头的行被视为注释并被忽略。
• 空行将被忽略。
• 未加引号和双引号（"）的值会应用插值。
• 每行代表一个键值对。值可以选择性地用引号括起来。
  • VAR=VAL -> VAL
  • VAR="VAL" -> VAL
  • VAR='VAL' -> VAL
• 未加引号的值的内联注释前必须加一个空格。
  • VAR=VAL # comment -> VAL
  • VAR=VAL# not a comment -> VAL# not a comment
• 引号值的内联注释必须跟在闭合引号之后。
  • VAR="VAL # not a comment" -> VAL # not a comment
  • VAR="VAL" # comment -> VAL
• 单引号（'）值按字面意思使用。
  • VAR='$OTHER' -> $OTHER
  • VAR='${OTHER}' -> ${OTHER}
• 引号可以使用 \ 进行转义。
  • VAR='Let\'s go!' -> Let's go!
  • VAR="{\"hello\": \"json\"}" -> {"hello": "json"}
• 双引号值中支持常见的 shell 转义序列，包括 \n、\r、\t 和 \\。
  • VAR="some\tvalue" -> some value
  • VAR='some\tvalue' -> some\tvalue
  • VAR=some\tvalue -> some\tvalue

用 --env-file 替换

您可以在 .env 文件中为多个环境变量设置默认值，然后将该文件作为参数传递给 CLI。

这种方法的优势在于，您可以将文件存储在任何位置并为其命名，例如， 此文件路径是相对于执行 Docker Compose 命令的当前工作目录的。传递文件路径需使用 --env-file 选项：

$ docker compose --env-file ./config/.env.dev up

附加信息

• 如果您想临时覆盖已在 compose.yml 文件中引用的 .env 文件，此方法非常有用。例如，您可能拥有用于生产环境（.env.prod）和测试环境（.env.test）的不同 .env 文件。在以下示例中，有两个环境文件：.env 和 .env.dev。两者为 TAG 设置了不同的值。

  $ cat .env
  TAG=v1.5
  $ cat ./config/.env.dev
  TAG=v1.6
  $ cat compose.yml
  services:
    web:
      image: "webapp:${TAG}"
  

  如果命令行中未使用 --env-file，则默认加载 .env 文件：

  $ docker compose config
  services:
    web:
      image: 'webapp:v1.5'
  

  传递 --env-file 参数将覆盖默认文件路径：

  $ docker compose --env-file ./config/.env.dev config
  services:
    web:
      image: 'webapp:v1.6'
  

  当传递的 --env-file 参数为无效文件路径时，Compose 将返回错误：

  $ docker compose --env-file ./doesnotexist/.env.dev  config
  ERROR: Couldn't find env file: /home/user/./doesnotexist/.env.dev
  

• 您可以使用多个 --env-file 选项来指定多个环境文件，Docker Compose 会按顺序读取它们。后面的文件可以覆盖前面文件中的变量。

  $ docker compose --env-file .env --env-file .env.override up
  

• 在启动容器时，您可以从命令行覆盖特定的环境变量。

  $ docker compose --env-file .env.dev up -e DATABASE_URL=mysql://new_user:new_password@new_db:3306/new_database
  

本地 .env 个文件对比 .env 个文件

.env 文件也可用于声明 预定义的环境变量，这些变量用于控制 Compose 的行为以及要加载的文件。

当执行时未指定显式的 --env-file 标志，Compose 会在您的工作目录中查找 .env 文件（ PWD），并加载用于自身配置和插值的值。如果此文件中的值定义了 COMPOSE_FILE 预定义变量，从而导致项目目录被设置为另一个文件夹， 则 Compose 将在存在时加载第二个 .env 文件。这第二个 .env 文件的优先级较低。

此机制使得可以使用一组自定义变量作为覆盖来调用现有的 Compose 项目，而无需通过命令行传递环境变量。

$ cat .env
COMPOSE_FILE=../compose.yaml
POSTGRES_VERSION=9.3

$ cat ../compose.yaml 
services:
  db:
    image: "postgres:${POSTGRES_VERSION}"
$ cat ../.env
POSTGRES_VERSION=9.2

$ docker compose config
services:
  db:
    image: "postgres:9.3"

从 Shell 替换

您可以使用宿主机或执行 docker compose 命令的 shell 环境中现有的环境变量。这使您能够在运行时动态地将值注入到 Docker Compose 配置中。 例如，假设 shell 中包含 POSTGRES_VERSION=9.3，并且您提供了以下配置：

db:
  image: "postgres:${POSTGRES_VERSION}"

当您使用此配置运行 docker compose up 时，Compose 会在 shell 中查找 POSTGRES_VERSION 环境变量并代入其值。在此示例中，Compose 在运行配置前会将镜像解析为 postgres:9.3。

如果未设置环境变量，Compose 会将其替换为空字符串。在前面的示例中，如果未设置 POSTGRES_VERSION，则 image 选项的值为 postgres:。

注意

postgres: 不是有效的镜像引用。Docker 期望使用不带标签的引用（例如 postgres，默认指向最新镜像），或使用带标签的引用（例如 postgres:15）。