YAML 文件中使用环境变量参数详解

简介

在使用 YAML 文件（如 Docker Compose 文件 docker-compose.yml）进行配置编排时，经常需要根据不同环境动态传入参数（如数据库地址、端口、密码等）。环境变量的灵活使用，使 YAML 文件更具通用性和可维护性，避免硬编码敏感信息或环境特有配置。

为什么在 YAML 中使用环境变量

• 动态配置：支持在不同环境（开发、测试、生产）使用相同的 YAML 文件，传入不同配置。
• 安全性：避免在版本控制中泄露密码、密钥等敏感信息。
• 简化维护：统一管理环境变量，避免修改多个配置文件。

环境变量的定义和使用方式

1. 直接在 YAML 文件中定义环境变量

在 docker-compose.yml 文件中，可以在environment字段直接指定环境变量：

services:
  web:
    image: myapp
    environment:
      - APP_ENV=production
      - DB_HOST=192.168.1.100

缺点：配置固定，不灵活。

2. 使用宿主机环境变量

Docker Compose 支持直接在 YAML 文件中引用宿主机（执行环境）已定义的环境变量，语法类似 ${VAR_NAME}：

services:
  web:
    image: myapp
    environment:
      - APP_ENV=${APP_ENV}
      - DB_HOST=${DB_HOST}

• 如果宿主机没有设置对应变量，默认会置为空。
• 可以通过 shell 方式导出环境变量，如：

export APP_ENV=development
export DB_HOST=localhost
docker-compose up

3. 使用 .env 文件

指定env文件

docker compose --env-file ../.env up -d

Docker Compose 默认会读取当前目录下的 .env 文件，里面定义的变量可以在 docker-compose.yml 中用 ${VAR_NAME} 形式访问。

示例 .env 文件：

APP_ENV=staging
DB_HOST=db.example.com
DB_PASS=secret

docker-compose.yml：

services:
  web:
    image: myapp
    environment:
      - APP_ENV=${APP_ENV}
      - DB_HOST=${DB_HOST}
      - DB_PASS=${DB_PASS}

运行 docker-compose up 时，变量会自动替换为 .env 文件内的值。

优点：

• 变量文件与配置分离，更安全。
• 支持多个环境用不同 .env 文件管理。

Docker Compose 中环境变量的示例

version: '3.8'

services:
  app:
    image: myapp:latest
    environment:
      - NODE_ENV=${NODE_ENV:-development}    # 支持默认值
      - PORT=${PORT:-3000}
      - DATABASE_URL=${DATABASE_URL}
    ports:
      - "${PORT:-3000}:3000"
    volumes:
      - .:/usr/src/app

说明：

• ${VAR_NAME} 表示引用对应变量。
• ${VAR_NAME:-default} 语法表示如果变量未设置，使用默认值。
• 变量可定义在宿主机环境或 .env 文件中。

例如可以创建不同 .env 文件：

# .env.dev
NODE_ENV=development
PORT=3000
DATABASE_URL=mysql://dev_user:dev_pass@localhost:3306/dev_db

# .env.prod
NODE_ENV=production
PORT=80
DATABASE_URL=mysql://prod_user:prod_pass@dbserver:3306/prod_db

启动时指定不同环境变量即可：

cp .env.dev .env
docker-compose up

# 切换生产
cp .env.prod .env
docker-compose up

高级技巧和注意事项

• 环境变量的默认值
  docker-compose.yml 中支持 ${VARIABLE:-default} 语法，推荐使用为确保安全和可控配置。

• 变量替换失败处理
  如果没有默认值且环境变量未定义，启动时会报错。也可用 ${VARIABLE-default}（无冒号）表示空时使用默认。

• 使用 ${VARIABLE?error message}
  如果变量未定义则报错提示。防止忘记设置关键变量。如：

  environment:
    - SECRET_KEY=${SECRET_KEY?err}

• 避免敏感信息提交版本库
  将 .env 文件添加到 .gitignore，在 CI/CD 中通过安全的方式管理环境变量。

• 复用环境变量
  可以用 env_file 来指定一个或多个外部变量文件：

  services:
    app:
      image: myapp
      env_file:
        - common.env
        - app.env

• 在 shell 脚本或 CI 中传递环境变量
  在执行 docker-compose 之前通过 shell 或 CI 配置注入环境变量。

总结

• YAML 文件通过环境变量实现配置的灵活动态替换。
• 宿主机环境变量、.env 文件是主流的变量来源。
• 推荐使用默认值和错误提示语法增强配置健壮性。
• 合理管理敏感信息，加强安全性。

掌握环境变量的用法，能极大提升配置文件的复用性和环境适配能力，是容器化部署不可或缺的技巧。