跳转至

Docker Compose 环境变量格式

概述

在 Docker Compose 的 environment 配置中，有两种书写格式：

  • YAML 映射格式（key: value）
  • YAML 数组格式（- key=value）

无论使用哪种写法，最终在容器内部设置的环境变量都是相同的。

格式对比

YAML 映射格式（key: value）

YAML
1
2
3
4
5
environment:
  MYSQL_ROOT_PASSWORD: rootpass
  MYSQL_DATABASE: myapp
  MYSQL_USER: user
  MYSQL_PASSWORD: pass

YAML 数组格式（- key=value）

YAML
1
2
3
environment:
  - DATABASE_URL=mysql+pymysql://user:pass@db:3306/myapp
  - REDIS_URL=redis://redis:6379/0

语法解析

写法一：映射格式

  • 使用标准的 YAML 键值对语法
  • 更符合 YAML 的自然格式
  • 可读性更好，特别是对于复杂的值

写法二：数组格式

  • 使用 YAML 数组项，每个项是一个字符串
  • 字符串格式为 key=value
  • 更像是 shell 环境变量的写法

实际效果

两种写法都会在容器中设置相同的环境变量：

Bash
1
2
3
4
MYSQL_ROOT_PASSWORD=rootpass
MYSQL_DATABASE=myapp
DATABASE_URL=mysql+pymysql://user:pass@db:3306/myapp
REDIS_URL=redis://redis:6379/0

推荐使用场景

推荐使用映射格式（key: value）的情况

YAML
1
2
3
4
environment:
  DATABASE_URL: "mysql+pymysql://user:pass@db:3306/myapp"
  REDIS_URL: "redis://redis:6379/0"
  APP_CONFIG: '{"host": "localhost", "port": 3000}'  # 复杂值

优点：

  • 更清晰的语法高亮
  • 更容易处理包含特殊字符的值
  • 更好的可读性

推荐使用数组格式（- key=value）的情况

YAML
1
2
3
environment:
  - DATABASE_URL=mysql+pymysql://user:pass@db:3306/myapp
  - REDIS_URL=redis://redis:6379/0

适用场景：

  • 从现有脚本或命令行参数复制过来时
  • 值比较简单，没有特殊字符时

重要注意事项

1. 值中包含冒号的情况

YAML
1
2
3
4
5
6
7
# 推荐使用映射格式
environment:
  URL: "http://example.com:8080/path"   # 正确

# 数组格式可能会混淆
environment:
  - URL=http://example.com:8080/path   # 可能解析错误

2. 值中包含等号的情况

YAML
1
2
3
4
5
6
7
# 映射格式更安全
environment:
  CONNECTION_STRING: "host=localhost;port=3306;user=admin"

# 数组格式会有问题（错误示范）
environment:
  - CONNECTION_STRING=host=localhost;port=3306;user=admin  # 错误！会创建多个变量

3. 布尔值和数字

YAML
1
2
3
4
5
6
7
8
9
# 映射格式会保持类型
environment:
  DEBUG: true    # 布尔值
  PORT: 3000     # 数字

# 数组格式都会变成字符串
environment:
  - DEBUG=true   # 字符串 "true"
  - PORT=3000    # 字符串 "3000"

最佳实践建议

  1. 一致性：在同一个项目中保持统一的格式
  2. 复杂值：优先使用映射格式（key: value）
  3. 简单值：两种都可以，根据团队偏好选择
  4. 特殊字符：包含 :、= 等字符时一定使用映射格式