Docker Compose 环境变量配置完全指南

Docker Compose 环境变量配置完全指南

docs Source repo for Docker's Documentation 项目地址: https://gitcode.com/gh_mirrors/docs3/docs

前言

在 Docker Compose 的实际应用中，环境变量扮演着至关重要的角色。它们不仅能够帮助我们灵活配置应用行为，还能实现不同环境下的差异化部署。本文将全面解析 Docker Compose 预定义环境变量的使用方法，帮助开发者更好地掌握这一强大工具。

环境变量基础概念

环境变量是操作系统或应用程序运行时的动态值，它们可以影响进程的行为。在 Docker Compose 中，环境变量主要用于：

1. 控制 Compose 工具本身的行为
2. 在不同环境间传递配置参数
3. 实现配置的外部化管理

环境变量设置方法

Docker Compose 支持多种方式来设置或覆盖环境变量：

1. .env 文件：在项目目录下创建 .env 文件，每行定义一个变量
2. 命令行：在执行命令前直接设置变量
3. Shell 环境：在 shell 配置文件中预先设置变量

核心环境变量详解

1. COMPOSE_PROJECT_NAME

作用：设置项目名称，该名称会作为容器名称的前缀。

示例：

COMPOSE_PROJECT_NAME=myapp

启动后容器名称将类似 myapp-db-1 和 myapp-web-1。

优先级规则（从高到低）：

1. -p 命令行参数
2. COMPOSE_PROJECT_NAME 环境变量
3. Compose 文件中的 name 属性
4. 包含 Compose 文件的目录名
5. 当前工作目录名

命名规范：只能包含小写字母、数字、短横线和下划线，且必须以字母或数字开头。

2. COMPOSE_FILE

作用：指定 Compose 配置文件路径，支持多文件配置。

默认行为：未设置时，Compose 会依次查找当前目录及其父目录中的 compose.yaml 文件。

多文件配置示例：

COMPOSE_FILE=compose.yaml:compose.prod.yaml

路径分隔符：

• Linux/macOS：:（冒号）
• Windows：;（分号）

3. COMPOSE_PROFILES

作用：指定要启用的服务配置文件。

工作原理：Compose 会启动匹配指定 profile 的服务，以及所有未定义 profile 的服务。

多 profile 示例：

COMPOSE_PROFILES=frontend,debug

这将启用 frontend 和 debug profile 下的服务，以及所有无 profile 的服务。

4. COMPOSE_CONVERT_WINDOWS_PATHS

作用：控制是否将 Windows 路径格式转换为 Unix 风格。

取值：

• true/1：启用转换
• false/0：禁用转换（默认）

5. COMPOSE_PATH_SEPARATOR

作用：自定义 COMPOSE_FILE 中的路径分隔符。

默认值：

• Linux/macOS：:
• Windows：;

6. COMPOSE_IGNORE_ORPHANS

作用：是否忽略孤儿容器检测。

取值：

• true/1：忽略检测
• false/0：执行检测（默认）

7. COMPOSE_REMOVE_ORPHANS

作用：是否自动移除孤儿容器。

取值：

• true/1：自动移除
• false/0：仅警告（默认）

8. COMPOSE_PARALLEL_LIMIT

作用：设置并发引擎调用的最大并行度。

9. COMPOSE_ANSI

作用：控制 ANSI 控制字符的输出方式。

取值：

• auto：自动检测（默认）
• never：纯文本模式
• always/0：TTY 模式

10. COMPOSE_STATUS_STDOUT

作用：控制状态和进度消息的输出流。

取值：

• true/1：输出到 stdout
• false/0：输出到 stderr（默认）

11. COMPOSE_ENV_FILES

作用：指定环境文件路径，支持多文件配置。

示例：

COMPOSE_ENV_FILES=.env.dev,.env.secret

12. COMPOSE_MENU

作用：控制是否显示 Compose 导航菜单。

默认值：

• Docker Desktop 安装：1（启用）
• 其他方式安装：0（禁用）

13. COMPOSE_EXPERIMENTAL

作用：控制实验性功能的启用状态。

取值：

• true/1：启用（默认）
• false/0：禁用

14. COMPOSE_PROGRESS

作用：定义进度输出类型。

可选值：auto（默认）、tty、plain、json、quiet

环境变量使用建议

1. 优先使用 .env 文件：便于版本控制和团队共享
2. 敏感信息处理：避免将密码等敏感信息直接写入 .env 文件
3. 环境区分：为不同环境（开发、测试、生产）创建不同的环境变量文件
4. 文档记录：记录重要环境变量的用途和取值

常见问题解答

Q：环境变量冲突时如何处理？ A：Docker Compose 遵循特定的优先级规则，通常命令行参数 > 环境变量 > 配置文件。

Q：如何查看当前生效的环境变量？ A：可以在 Compose 命令前添加 env 命令查看，或使用 docker compose config 查看最终配置。

Q：环境变量支持哪些数据类型？ A：环境变量本质上都是字符串，应用内部会根据需要进行类型转换。

总结

掌握 Docker Compose 环境变量的使用是高效容器编排的关键。通过合理配置这些变量，开发者可以实现灵活的部署策略，简化多环境管理，提高工作效率。建议读者在实际项目中多加练习，逐步掌握各种环境变量的最佳实践。

docs Source repo for Docker's Documentation 项目地址: https://gitcode.com/gh_mirrors/docs3/docs