切换语言

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

目录

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

插值还可用于在运行时将值插入到 Compose 文件中，然后使用该值将变量传递到容器的环境中

下面是一个简单的示例：

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

当您运行docker compose up这webservice 在 Compose 文件中定义的 app 在镜像中插值webapp:v1.5该 API 在.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如果 set 且非空，否则退出并显示错误
    • ${VAR?error}-> 值VAR如果设置，否则退出并显示错误
  • 替代值
    • ${VAR:+replacement} -> replacement如果VAR已设置且非空，否则为空
    • ${VAR+replacement} -> replacement如果VAR已设置，否则为空

有关更多信息，请参阅 Compose 规范中的插值。

使用插值设置变量的方法

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

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

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

您可以通过运行docker compose config --environment.

.env文件

一.env文件是一个文本文件，用于定义运行时应可用于插值的变量docker compose up.此文件通常包含变量的键值对，它允许您在一个位置集中和管理配置。这.envfile 在需要存储多个变量时非常有用。

这.envfile 是设置变量的默认方法。这.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文件中，您可以直接在compose.yml使用environment属性.例如，如果您的.envfile 包含环境变量DEBUG=1和您的compose.yml文件如下所示：

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

    Docker Compose 取代了${DEBUG}替换为.env文件

    重要

    在.env文件作为环境变量添加到容器环境中。

  • 您可以将.env文件，然后使用--env-fileCLI 中的选项，以便 Compose 可以导航到该地址。

  • 你.env文件可以被另一个文件覆盖.env如果是替换为--env-file.

重要

代入.envfiles 是 Docker Compose CLI 的一项功能。

运行时 Swarm 不支持docker stack deploy.

.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

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

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

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

其他信息：

  • 如果要临时覆盖.env文件中已引用的文件compose.yml文件。例如，您可能有不同的.env用于生产 （.env.prod） 和测试 （.env.test). 在以下示例中，有两个环境文件.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未在命令行中使用，则.envfile 的默认加载方式：
    $ 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

当地.envfile 与.env文件

一.envfile 还可用于声明用于控制 Compose 行为和要加载的文件的预定义环境变量。

在没有显式--env-file标志中，Compose 会搜索.env文件 （PWD） 并加载值 用于自配置和插值。如果此文件中的值定义了COMPOSE_FILE预定义变量，这会导致项目目录被设置为另一个文件夹。 Compose 将加载第二个.env文件（如果存在）。这第二个.envfile 的优先级较低。

借助此机制，您可以使用一组自定义变量作为替换来调用现有 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 中替换

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

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

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

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

注意

postgres:不是有效的镜像引用。Docker 需要一个没有标签的引用，比如postgres默认为最新镜像，或者带有postgres:15.