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

Compose 已经附带了预定义的环境变量。它还继承了常见的 Docker CLI 环境变量，例如DOCKER_HOST和DOCKER_CONTEXT。有关详细信息，请参阅 Docker CLI 环境变量参考。

本页包含有关如何设置或更改以下预定义环境变量（如果需要）的信息：

  • COMPOSE_CONVERT_WINDOWS_PATHS
  • COMPOSE_FILE
  • COMPOSE_PROFILES
  • COMPOSE_PROJECT_NAME
  • DOCKER_CERT_PATH
  • COMPOSE_PARALLEL_LIMIT
  • COMPOSE_IGNORE_ORPHANS
  • COMPOSE_REMOVE_ORPHANS
  • COMPOSE_PATH_SEPARATOR
  • 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:配置文件中的顶级变量（或name:使用指定的一系列配置文件中的最后一个变量-f）
  4. basename包含配置文件的项目目录（或包含使用指定的第一个配置文件-f）
  5. basename如果未指定配置文件，则为当前目录的

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

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

撰写_文件

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

  • 默认行为：如果未提供，Compose会在当前目录中查找名为compose.yaml或的文件，如果未找到，Compose 会递归搜索每个父目录，直到找到该名称的文件。docker-compose.yaml
  • 默认分隔符：指定多个 Compose 文件时，路径分隔符默认为：
    • Mac 和 Linux：（:冒号），
    • Windows：（;分号）。

路径分隔符也可以使用自定义COMPOSE_PATH_SEPARATOR。

例子：COMPOSE_FILE=docker-compose.yml:docker-compose.prod.yml。

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

组合配置文件

指定在执行时启用的一个或多个配置文件compose up。具有匹配配置文件的服务以及尚未定义配置文件的任何服务都会启动。

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

  • 默认分隔符：使用逗号作为分隔符指定配置文件列表。

示例：COMPOSE_PROFILES=frontend,debug
此示例启用与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_PARALLEL_LIMIT

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

组合_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

允许您指定 Compose 在--env-file未使用时应使用哪些环境文件。

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

COMPOSE_ENV_FILES=.env.envfile1, .env.envfile2

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

组合菜单

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

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

笔记

适用于 Docker Compose 版本 2.26.0 及更高版本以及 Docker Desktop 版本 4.29 及更高版本

组合_实验

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

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

笔记

适用于 Docker Compose 版本 2.26.0 及更高版本以及 Docker Desktop 版本 4.29 及更高版本

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使用经典构建器来构建图像。