使用 Compose 设置环境变量的方法

使用 Compose，您可以通过多种方式在容器中设置环境变量。您可以使用 Compose 文件或 CLI。

请注意，每个方法都受 环境变量优先级的约束。

提示

不要使用环境变量将敏感信息（例如密码）传递到容器中。使用 秘密来代替。

撰写文件

替换为 .env 文件

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

该.env文件是在容器中设置环境变量的默认方法。该.env文件应放置在项目目录的根目录中您的文件旁边compose.yaml。有关格式化环境文件的详细信息，请参阅 环境文件的语法。

下面是一个简单的例子：

$ cat .env
TAG=v1.5

$ cat compose.yml
services:
  web:
    image: "webapp:${TAG}"

当您运行时docker compose up，webCompose 文件中定义的服务 将插入webapp:v1.5到文件中设置的图像中.env。您可以使用config 命令来验证这一点 ，该命令将解析的应用程序配置打印到终端：

$ docker compose config

services:
  web:
    image: 'webapp:v1.5'

附加信息

  • 从 Docker Compose 版本 2.24.0 开始，您可以.env使用 属性将文件设置为可选env_file。当required设置为false并且.env文件丢失时，Compose 会默默地忽略该条目。

    env_file:
  - path: ./default.env
    required: true # default
  - path: ./override.env
    required: false

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

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

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

  • 您可以使用属性中的多个文件 .env， Docker Compose会按照指定的顺序读取它们。如果在多个文件中定义相同的变量，则最后一个定义优先：compose.ymlenv_file

    services:
  webapp:
    image: my-webapp-image
    env_file:
      - .env
      - .env.override

  • 您可以将.env文件放置在项目目录根目录之外的位置，然后使用以下方法之一，以便 Compose 可以导航到该文件：

  • .env可以使用命令行覆盖文件 中的值docker compose run -e。

  • 如果 您的.env文件被替换为..env--env-file

重要的

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

Swarm运行时不支持docker stack deploy。

使用环境属性

您可以直接在 Compose 文件中设置环境变量，而无需使用文件.env， environment并在compose.yml.它的工作方式与docker run -e VARIABLE=VALUE ...

web:
  environment:
    - DEBUG=1

有关如何使用它的更多示例，请参阅 environment属性。

附加信息

  • 您可以选择不设置值并将环境变量从 shell 直接传递到容器。它的工作方式与以下相同docker run -e VARIABLE ...：

    web:
  environment:
    - DEBUG

    容器中变量的值DEBUG取自运行 Compose 的 shell 中同一变量的值。请注意，在这种情况下，如果DEBUG未设置 shell 环境中的变量，则不会发出警告。

  • 您还可以利用 插值。

    web:
  environment:
    - DEBUG=${DEBUG}

    结果与上面的结果类似，但如果DEBUG未在 shell 环境中设置变量，Compose 会向您发出警告。

使用 env_file 属性

该 env_file属性允许您.env在 Compose 应用程序中使用多个文件。它还可以帮助您将环境变量与主配置文件分开，从而提供更有组织且更安全的方式来管理敏感信息，因为您不需要将文件放在.env项目目录的根目录中。

它的工作方式与 相同docker run --env-file=FILE ...。

web:
  env_file:
    - web-variables.env

附加信息

  • 如果指定了多个文件，则会按顺序评估它们，并且可以覆盖先前文件中设置的值。
  • 文件中声明的环境变量.env不能在 Compose 文件中再次单独引用。
  • 如果同时使用env_file和environment属性，则设置的环境变量environment优先。
  • .env属性中指定的文件路径env_file是相对于文件位置的compose.yml。
  • .env可以使用命令行覆盖文件 中的值docker compose run -e。
  • 如果 您的.env文件被替换为..env--env-file
  • 从 Docker Compose 版本 2.24.0 开始，您可以.env使用该字段将文件设置为可选required。当required设置为false并且.env文件丢失时，Compose 会默默地忽略该条目。
    env_file:
  - path: ./default.env
    required: true # default
  - path: ./override.env
    required: false

从外壳中替代

您可以使用主机或执行docker compose命令的 shell 环境中的现有环境变量。这允许您在运行时动态地将值注入到 Docker Compose 配置中。

例如，假设 shell 包含POSTGRES_VERSION=9.3并且您提供以下配置：

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

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

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

笔记

postgres:不是有效的图像参考。 Docker 期望引用不带标签（例如postgres默认为最新映像）或带标签（例如postgres:15.

重要的

shell 环境中设置的值会覆盖.env文件、environment属性和env_file属性中设置的值。有关详细信息，请参阅 环境变量优先级。

命令行界面

替换为 --env-file

您可以在环境文件中设置多个环境变量的默认值， 然后将该文件作为 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命令行中未使用，则.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

使用 docker compose run --env 设置环境变量

与 类似，您可以使用或其缩写形式docker run --env临时设置环境变量：docker compose run --envdocker compose run -e

$ docker compose run -e DEBUG=1 web python console.py

附加信息

  • 您还可以通过不给定值的方式从 shell 传递变量：

    $ docker compose run -e DEBUG web python console.py

    容器中变量的值DEBUG取自运行 Compose 的 shell 中同一变量的值。

更多资源