在 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 文件中,使用
environment
属性 - 使用
env-file
属性和 环境文件 - 从命令行
- 从您的 shell
更改或设置任何环境变量时,请注意 环境变量优先级。
配置
COMPOSE_PROJECT_NAME
设置项目名称。此值在启动时与服务名称一起预先添加到容器的名称中。
例如,如果您的项目名称为 myapp
,并且它包含两个服务 db
和 web
,那么 Compose 启动的容器分别名为 myapp-db-1
和 myapp-web-1
。
Compose 可以通过不同的方式设置项目名称。每种方法的优先级级别(从高到低)如下所示
-p
命令行标志COMPOSE_PROJECT_NAME
- 配置文件中的顶级
name:
变量(或使用-f
指定的一系列配置文件中的最后一个name:
) - 包含配置文件的项目目录的
basename
(或包含使用-f
指定的第一个配置文件的目录) - 如果未指定配置文件,则为当前目录的
basename
项目名称必须仅包含小写字母、数字、连字符和下划线,并且必须以小写字母或数字开头。如果项目目录或当前目录的 basename
违反此约束,则必须使用其他机制之一。
另请参阅 命令行选项概述 和 使用 -p
指定项目名称。
COMPOSE_FILE
指定 Compose 文件的路径。支持指定多个 Compose 文件。
- 默认行为:如果未提供,Compose 会在当前目录中查找名为
compose.yaml
或docker-compose.yaml
的文件,如果未找到,Compose 会递归搜索每个父目录,直到找到该名称的文件。 - 默认分隔符:指定多个 Compose 文件时,路径分隔符默认情况下为
- Mac 和 Linux:
:
(冒号), - Windows:
;
(分号)。
- Mac 和 Linux:
路径分隔符也可以使用 COMPOSE_PATH_SEPARATOR
自定义。
示例:COMPOSE_FILE=docker-compose.yml:docker-compose.prod.yml
。
另请参阅 命令行选项概述 和 使用 -f
指定一个或多个 Compose 文件的名称和路径。
COMPOSE_PROFILES
指定在 compose up
执行时要启用的一个或多个配置文件。具有匹配配置文件的服务将启动,以及任何未定义配置文件的服务。
例如,使用 COMPOSE_PROFILES=frontend
调用 docker compose up
会选择具有 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 上为
;
。
- 在 macOS 和 Linux 上为
COMPOSE_IGNORE_ORPHANS
启用后,Compose 不会尝试检测项目的孤立容器。
- 支持的值
true
或1
,启用,false
或0
,禁用。
- 默认为:
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
允许您指定 Compose 应该使用哪些环境文件,如果未使用 --env-file
。
使用多个环境文件时,使用逗号作为分隔符。例如,
COMPOSE_ENV_FILES=.env.envfile1, .env.envfile2
如果未设置 COMPOSE_ENV_FILES
,并且您未在 CLI 中提供 --env-file
,则 Docker Compose 会使用默认行为,即在项目目录中查找 .env
文件。
COMPOSE_MENU
启用后,Compose 会显示一个导航菜单,您可以在其中选择在 Docker Desktop 中打开 Compose 堆栈,启用 watch
模式,或使用 Docker Debug。
- 支持的值
true
或1
,启用,false
或0
,禁用。
- 默认为:
1
(如果您通过 Docker Desktop 获得了 Docker Compose),否则默认值为0
。
注意
在 Docker Compose 版本 2.26.0 及更高版本以及 Docker Desktop 版本 4.29 及更高版本中可用
COMPOSE_EXPERIMENTAL
这是一个选择退出变量。关闭它会停用实验性功能,例如导航菜单或 同步文件共享。
- 支持的值
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
使用经典构建器构建镜像。