services:
  app:
    image: myapp:latest

    # 语法一：映射格式（推荐，更清晰）
    environment:
      NODE_ENV: production
      DATABASE_URL: postgresql://user:pass@db:5432/mydb
      LOG_LEVEL: info
      CACHE_TTL: "3600"        # 数字值建议加引号

    # 语法二：列表格式
    # environment:
    #   - NODE_ENV=production
    #   - DATABASE_URL=postgresql://user:pass@db:5432/mydb
    #   - LOG_LEVEL=info

services:
  app:
    environment:
      # 显式设置为空字符串
      DEBUG: ""

      # 从宿主机继承（仅映射格式支持）
      HOME:        # 继承宿主机的 $HOME
      USER:        # 继承宿主机的 $USER
      PATH: /usr/local/bin:/usr/bin:/bin  # 可覆盖

services:
  app:
    environment:
      # 引用 .env 文件或 shell 中的变量
      DATABASE_URL: postgresql://${DB_USER}:${DB_PASS}@db:5432/${DB_NAME}

      # 带默认值
      LOG_LEVEL: ${LOG_LEVEL:-info}
      PORT: ${PORT:-3000}

      # 仅在变量存在时使用（否则为空）
      EXTRA_CONFIG: ${EXTRA_CONFIG:-}

# 项目结构
myproject/
├── .env              # ← Compose 自动加载
├── compose.yaml
└── ...

# .env — 注意：这不是 shell 脚本，但语法类似

# 注释行
# 空行会被忽略

# 基本赋值
DB_USER=admin
DB_PASS=s3cretP@ss
DB_NAME=myapp

# 值包含空格时必须加引号
APP_TITLE=My Application

# 单引号（不解释变量）
GREETING='Hello $USER'

# 双引号（解释变量）
FULL_GREETING="Hello $USER"

# 可用于端口、版本等
POSTGRES_VERSION=16
WEB_PORT=8080

# .env
# DB_USER=admin
# DB_PASS=s3cretP@ss
# DB_NAME=myapp

# compose.yaml
services:
  db:
    image: postgres:${POSTGRES_VERSION:-16}-alpine
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASS}
      POSTGRES_DB: ${DB_NAME}

  web:
    image: myapp:latest
    ports:
      - "${WEB_PORT:-8080}:3000"
    environment:
      DATABASE_URL: postgresql://${DB_USER}:${DB_PASS}@db:5432/${DB_NAME}

# 关键区别演示
services:
  app:
    ports:
      - "${WEB_PORT}:3000"      # ← .env 变量，由 Compose 解析
    environment:
      PORT: "3000"               # ← 容器环境变量，传入容器
      DB_HOST: db                # ← 容器环境变量

services:
  app:
    image: myapp:latest
    env_file:
      - app.env                # 相对路径（相对于 compose.yaml）
      - common.env

# app.env
NODE_ENV=production
LOG_LEVEL=info
DATABASE_URL=postgresql://user:pass@db:5432/mydb
API_KEY=sk-abc123xyz

services:
  app:
    env_file:
      - common.env             # 通用配置（先加载）
      - app.env                # 应用配置（后加载，会覆盖同名变量）
      - secrets.env            # 敏感配置（最后加载）

services:
  app:
    env_file:
      - path: app.env         # 长语法
        required: true         # 必须存在，否则报错（Compose V2.24+）

      - path: optional.env
        required: false        # 可选，不存在不报错

# app.env

# ✅ 正确
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp

# ✅ 值包含空格
APP_NAME=My Application

# ✅ 引号（引号会成为值的一部分 ⚠️）
DB_PASS="s3cret"     # 容器内值为 "s3cret"（含引号！）
DB_PASS2='s3cret'    # 同上

# ❌ 不支持变量引用
HOME_DIR=$HOME       # 字面值 "$HOME"，不会展开

# ❌ 不支持 export
export DB_HOST=...   # 会将 "export DB_HOST" 作为变量名

# compose.yaml
services:
  demo:
    image: alpine:3.20
    command: ["sh", "-c", "echo VAR=$VAR && sleep 3600"]
    env_file:
      - demo.env
    environment:
      VAR: "from-environment"

# demo.env
VAR=from-env-file

# 实验 1：使用 environment 值
docker compose up
# 输出: VAR=from-environment

# 实验 2：通过命令行注入（更高优先级）
VAR=from-shell docker compose up
# 输出: VAR=from-shell

# 实验 3：run -e 注入
docker compose run -e VAR=from-run-flag demo
# 输出: VAR=from-run-flag

services:
  app:
    environment:
      # 基本引用
      DB_HOST: ${DB_HOST}

      # 带默认值（变量未设置时使用）
      DB_PORT: ${DB_PORT:-5432}

      # 带默认值（变量为空或未设置时使用）
      DB_NAME: ${DB_NAME:-myapp}

      # 错误提示（变量未设置时报错）
      DB_PASS: ${DB_PASS:?数据库密码必须设置}

      # 仅在变量为空或未设置时使用默认值
      LOG_LEVEL: ${LOG_LEVEL-default}

      # 仅在变量未设置时使用默认值（空字符串时不触发）
      CACHE_TTL: ${CACHE_TTL-3600}

services:
  app:
    entrypoint: /bin/sh -c
    command:
      - |
        echo "Literal dollar: $$HOME"
        # 不会被 Compose 替换，传入容器后由 shell 解释

project/
├── .env                  # 默认（开发）
├── .env.staging          # 预发布
├── .env.production       # 生产
├── compose.yaml
└── compose.prod.yaml

# 开发环境
docker compose up

# 生产环境
docker compose -f compose.yaml -f compose.prod.yaml --env-file .env.production up -d

services:
  app:
    image: myapp:latest
    env_file:
      - env/common.env          # 通用配置
      - env/${APP_ENV:-dev}.env # 环境特定配置

# env/common.env
LOG_FORMAT=json
APP_NAME=myapp

# env/dev.env
LOG_LEVEL=debug
DATABASE_URL=postgresql://dev:dev@localhost:5432/myapp_dev

# env/prod.env
LOG_LEVEL=warn
DATABASE_URL=postgresql://prod:prod@db:5432/myapp

# compose.yaml — 通用基础配置
services:
  app:
    image: ${DOCKER_REGISTRY:-docker.io}/${DOCKER_REPO:-myorg}/myapp:${APP_VERSION:-latest}
    ports:
      - "${APP_PORT:-8080}:3000"
    environment:
      NODE_ENV: ${NODE_ENV:-development}
      LOG_LEVEL: ${LOG_LEVEL:-debug}
      DATABASE_URL: ${DATABASE_URL}
      REDIS_URL: ${REDIS_URL:-redis://cache:6379}

# 不要这样做！compose.yaml 会进入版本控制
services:
  db:
    environment:
      POSTGRES_PASSWORD: mysecretpassword    # ❌ 密码明文

# compose.yaml
services:
  db:
    environment:
      POSTGRES_PASSWORD: ${DB_PASS}

# .env（加入 .gitignore）
DB_PASS=mysecretpassword

# .gitignore
.env
.env.*
!.env.example

# .env.example（提交到版本控制，作为模板）
DB_USER=
DB_PASS=
DB_NAME=myapp

services:
  db:
    image: postgres:16
    secrets:
      - db_password
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

# Python
import os
db_url = os.environ.get("DATABASE_URL", "sqlite:///default.db")
log_level = os.getenv("LOG_LEVEL", "info")

// Node.js
const dbUrl = process.env.DATABASE_URL || "sqlite:///default.db";
const port = parseInt(process.env.PORT || "3000");

// Go
import "os"
dbURL := os.Getenv("DATABASE_URL")
if dbURL == "" {
    dbURL = "sqlite:///default.db"
}

# 查看容器的所有环境变量
docker compose exec app env

# 查看特定变量
docker compose exec app printenv DATABASE_URL

# 在 entrypoint 脚本中调试
docker compose exec app sh -c 'echo $DATABASE_URL'

services:
  nginx:
    image: nginx:alpine
    volumes:
      - ./nginx.template:/etc/nginx/templates/default.conf.template:ro
    environment:
      BACKEND_HOST: app
      BACKEND_PORT: "3000"
      SERVER_NAME: myapp.example.com

# nginx.template — Nginx 官方镜像支持 envsubst 自动替换
server {
    listen 80;
    server_name ${SERVER_NAME};

    location / {
        proxy_pass http://${BACKEND_HOST}:${BACKEND_PORT};
    }
}

# 查看完整的解析后配置（含变量替换结果）
docker compose config

# 查看特定服务的环境变量
docker compose config --format json | jq '.services.app.environment'

# 验证 .env 加载
docker compose config | grep "VAR_NAME"