在 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

覆盖方法

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

• 通过一个 .env 文件位于您的工作目录中
• 从命令行
• 从您的 shell

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

配置

COMPOSE_PROJECT_NAME

设置项目名称。该值将在启动时与服务名称一起作为前缀，添加到容器名称中。

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

Compose 可以通过多种方式设置项目名称。各方法的优先级（从高到低）如下：

1. -p 命令行标志
2. COMPOSE_PROJECT_NAME
3. 来自配置文件（或使用 -f 指定的一系列配置文件中的最后一个）的顶层 name: 变量
4. 项目目录的 basename，其中包含配置文件（或使用 -f 指定的第一个配置文件）
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，且您在命令行中未提供 --env-file，Docker Compose 将使用默认行为，即在项目目录中查找 .env 文件。

COMPOSE_MENU

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

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

COMPOSE_EXPERIMENTAL

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

• 支持的值：
  • 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 将使用经典构建器来构建镜像。