Docker Compose环境变量插值使用指南

Docker Compose环境变量插值使用指南

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

前言

在Docker Compose项目中使用环境变量插值(Interpolation)是一项非常实用的功能，它允许我们在不修改Compose文件的情况下，动态地注入配置值。本文将全面介绍Docker Compose中环境变量插值的使用方法、语法规则以及各种应用场景。

什么是环境变量插值

环境变量插值是指在Compose文件中使用变量占位符，这些占位符会在运行时被实际的值替换。这种方式带来了以下优势：

1. 配置灵活性：可以轻松切换不同环境配置
2. 安全性：敏感信息不需要硬编码在配置文件中
3. 可维护性：集中管理变量值，便于统一修改

基本使用示例

让我们从一个简单的例子开始：

$ cat .env
TAG=v1.5

$ cat compose.yaml
services:
  web:
    image: "webapp:${TAG}"

当运行docker compose up时，Compose会自动将${TAG}替换为.env文件中定义的v1.5，最终使用的镜像是webapp:v1.5。

插值语法详解

Docker Compose支持多种插值语法格式：

基础语法

• ${VAR}：直接替换为VAR变量的值
• $VAR：简写形式，功能同上

高级语法

1. 默认值设置

   • ${VAR:-default}：如果VAR已设置且非空，则使用VAR的值，否则使用default
   • ${VAR-default}：如果VAR已设置(即使为空)，则使用VAR的值，否则使用default

2. 必需值设置

   • ${VAR:?error}：如果VAR未设置或为空，则显示错误信息并退出
   • ${VAR?error}：如果VAR未设置(允许为空)，则显示错误信息并退出

3. 替代值设置

   • ${VAR:+replacement}：如果VAR已设置且非空，则使用replacement，否则使用空字符串
   • ${VAR+replacement}：如果VAR已设置(允许为空)，则使用replacement，否则使用空字符串

变量设置方式

Docker Compose支持多种方式来设置变量，这些方式有明确的优先级顺序：

1. Shell环境变量

直接在shell中设置的变量优先级最高：

export POSTGRES_VERSION=9.6
docker compose up

2. 本地.env文件

项目根目录下的.env文件是默认的变量来源：

$ cat .env
DB_HOST=localhost
DB_PORT=5432

3. 通过--env-file指定文件

可以使用--env-file参数指定自定义的环境变量文件：

docker compose --env-file config/prod.env up

.env文件详解

.env文件是管理Compose变量的主要方式，其语法规则如下：

1. 注释以#开头

2. 空行会被忽略

3. 支持三种引用方式：

   • 无引号：VAR=value
   • 双引号：VAR="value"（支持转义和插值）
   • 单引号：VAR='value'（字面值，不进行插值）

4. 特殊字符处理：

   • 转义字符：VAR="Let\'s go"
   • 常见转义序列：\n, \t等（仅在双引号中有效）

实际应用场景

多环境配置

通过不同的.env文件管理不同环境的配置：

# 开发环境
docker compose --env-file .env.dev up

# 生产环境
docker compose --env-file .env.prod up

动态镜像版本控制

services:
  app:
    image: "myapp:${APP_VERSION:-latest}"

条件式配置

services:
  web:
    deploy:
      replicas: ${PRODUCTION:+3}
      # 仅在PRODUCTION变量设置且非空时设置3个副本

最佳实践

1. 敏感信息管理：不要将密码等敏感信息直接提交到版本控制，可以考虑使用.env.example模板文件

2. 变量命名规范：使用大写字母和下划线，如DB_HOST

3. 默认值设置：为关键变量设置合理的默认值

4. 文档说明：在项目文档中说明需要设置的环境变量

5. 验证配置：使用docker compose config命令验证变量替换结果

常见问题解决

1. 变量未替换：检查变量名拼写是否正确，确保变量来源正确

2. 空值问题：使用:-语法设置合理的默认值

3. 特殊字符处理：对于包含特殊字符的值，使用适当的引用方式

4. 优先级混淆：记住shell变量优先级高于.env文件

总结

Docker Compose的环境变量插值功能为容器编排提供了极大的灵活性。通过合理使用各种插值语法和变量设置方式，我们可以实现：

• 一套Compose文件适应多环境部署
• 敏感信息与配置分离
• 动态调整容器配置
• 简化团队协作配置管理

掌握这些技巧将显著提升你的Docker Compose使用体验和工作效率。

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