在 Docker Compose 中设置或更改预定义的环境变量

目录

Compose 已经自带预定义的环境变量。它还继承常见的 Docker CLI 环境变量，例如DOCKER_HOST和DOCKER_CONTEXT。详情请参见Docker CLI 环境变量参考。

此页面包含有关如何在需要时设置或更改以下预定义环境变量的信息

  • COMPOSE_PROJECT_NAME
  • COMPOSE_FILE
  • COMPOSE_PROFILES
  • COMPOSE_CONVERT_WINDOWS_PATHS
  • COMPOSE_PATH_SEPARATOR
  • COMPOSE_IGNORE_ORPHANS
  • COMPOSE_REMOVE_ORPHANS
  • COMPOSE_PARALLEL_LIMIT
  • COMPOSE_ANSI
  • COMPOSE_STATUS_STDOUT
  • COMPOSE_ENV_FILES
  • COMPOSE_MENU
  • COMPOSE_EXPERIMENTAL

覆盖方法

您可以设置或更改预定义的环境变量

更改或设置任何环境变量时，请注意环境变量优先级。

配置

COMPOSE_PROJECT_NAME

设置项目名称。此值在启动时与服务名称一起添加到容器的名称前面。

例如，如果您的项目名称为myapp，并且它包含两个服务db和web，则 Compose 分别启动名为myapp-db-1和myapp-web-1的容器。

Compose 可以通过不同的方式设置项目名称。每种方法的优先级（从高到低）如下所示

  1. -p命令行标志
  2. COMPOSE_PROJECT_NAME
  3. 来自配置文件的顶级name:变量（或使用-f指定的一系列配置文件中的最后一个name:）
  4. 包含配置文件（或包含使用-f指定的第一个配置文件）的项目目录的basename
  5. 如果没有指定配置文件，则为当前目录的basename

项目名称必须仅包含小写字母、十进制数字、短划线和下划线，并且必须以小写字母或十进制数字开头。如果项目目录或当前目录的basename违反此约束，则必须使用其他机制之一。

另请参见命令行选项概述和使用-p指定项目名称。

COMPOSE_FILE

指定 Compose 文件的路径。支持指定多个 Compose 文件。

  • 默认行为：如果未提供，Compose 将在当前目录中查找名为compose.yaml的文件，如果未找到，则 Compose 将递归搜索每个父目录，直到找到同名文件。
  • 指定多个 Compose 文件时，路径分隔符默认为

    • Mac 和 Linux：:（冒号）

    • Windows：;（分号）例如

      COMPOSE_FILE=docker-compose.yml:docker-compose.prod.yml
    也可以使用COMPOSE_PATH_SEPARATOR自定义路径分隔符。

另请参见命令行选项概述和使用-f指定一个或多个 Compose 文件的名称和路径。

COMPOSE_PROFILES

指定在运行docker compose up时要启用的一个或多个配置文件。

具有匹配配置文件的服务将启动，以及任何未定义配置文件的服务。

例如，使用COMPOSE_PROFILES=frontend调用docker compose up将选择具有frontend配置文件的服务以及任何未指定配置文件的服务。

如果指定多个配置文件，请使用逗号作为分隔符。

以下示例启用同时匹配frontend和debug配置文件的服务，以及没有配置文件的服务。

COMPOSE_PROFILES=frontend,debug

另请参见 使用 Compose 的配置文件 和 --profile 命令行选项。

COMPOSE_CONVERT_WINDOWS_PATHS

启用后，Compose 会将卷定义中的 Windows 风格路径转换为 Unix 风格路径。

  • 支持的值
    • true 或 1，启用
    • false 或 0，禁用
  • 默认值：0

COMPOSE_PATH_SEPARATOR

为COMPOSE_FILE中列出的项目指定不同的路径分隔符。

  • 默认为
    • 在 macOS 和 Linux 上为:
    • 在 Windows 上为;

COMPOSE_IGNORE_ORPHANS

启用后，Compose 不会尝试检测项目的孤立容器。

  • 支持的值
    • true 或 1，启用
    • false 或 0，禁用
  • 默认值：0

COMPOSE_REMOVE_ORPHANS

启用后，Compose 会在更新服务或堆栈时自动删除孤立容器。孤立容器是由先前配置创建的，但在当前compose.yaml文件中不再定义的容器。

  • 支持的值
    • true 或 1，启用自动删除孤立容器
    • false 或 0，禁用自动删除。Compose 将改为显示有关孤立容器的警告。
  • 默认值：0

COMPOSE_PARALLEL_LIMIT

指定并发引擎调用的最大并行级别。

COMPOSE_ANSI

指定何时打印 ANSI 控制字符。

  • 支持的值
    • auto，Compose 检测是否可以使用 TTY 模式。否则，使用纯文本模式
    • never，使用纯文本模式
    • always 或 0，使用 TTY 模式
  • 默认值：auto

COMPOSE_STATUS_STDOUT

启用后，Compose 会将其内部状态和进度消息写入stdout而不是stderr。默认值为 false，以便清晰地区分 Compose 消息和容器日志之间的输出流。

  • 支持的值
    • true 或 1，启用
    • false 或 0，禁用
  • 默认值：0

COMPOSE_ENV_FILES

允许您指定如果未使用--env-file，Compose 应使用的环境文件。

使用多个环境文件时，请使用逗号作为分隔符。例如

COMPOSE_ENV_FILES=.env.envfile1, .env.envfile2

如果未设置COMPOSE_ENV_FILES，并且您未在 CLI 中提供--env-file，则 Docker Compose 使用默认行为，即在项目目录中查找.env文件。

COMPOSE_MENU

在 Docker Compose 版本 2.26.0 中引入

启用后，Compose 会显示一个导航菜单，您可以在其中选择在 Docker Desktop 中打开 Compose 堆栈，启用 watch 模式 或使用 Docker Debug。

  • 支持的值
    • true 或 1，启用
    • false 或 0，禁用
  • 默认值：如果您通过 Docker Desktop 获取 Docker Compose，则为1，否则为0

COMPOSE_EXPERIMENTAL

在 Docker Compose 版本 2.26.0 中引入

这是一个选择退出变量。关闭后，它将停用实验性功能，例如导航菜单或 同步文件共享。

  • 支持的值
    • true 或 1，启用
    • false 或 0，禁用
  • 默认值：1

Compose V2 中不支持

以下环境变量在 Compose V2 中无效。有关更多信息，请参见 迁移到 Compose V2。

  • COMPOSE_API_VERSION 默认情况下，API 版本与服务器协商。使用DOCKER_API_VERSION。
    请参见 Docker CLI 环境变量参考 页面。
  • COMPOSE_HTTP_TIMEOUT
  • COMPOSE_TLS_VERSION
  • COMPOSE_FORCE_WINDOWS_HOST
  • COMPOSE_INTERACTIVE_NO_CLI
  • COMPOSE_DOCKER_CLI_BUILD 使用DOCKER_BUILDKIT在 BuildKit 和经典构建器之间进行选择。如果DOCKER_BUILDKIT=0，则docker compose build使用经典构建器来构建镜像。