使用Docker Compose的--env-file参数时环境变量不生效问题求助

我正在查阅Docker Compose环境变量相关文档并尝试复现配置：

配置文件 #

• .env.docker1：

API_PORT=5001

• .env.docker2：

API_PORT=5002

• compose.yml：

volumes:
  app-data:

services:
  api:
    build: .
    restart: unless-stopped
    command: gunicorn ... 'main:app()'
    env_file:
      - .env.docker1
    ports:
      - "$API_PORT:5000"

执行结果 #

• 运行 docker compose up，API_PORT为5001，符合预期
• 运行 docker compose --env-file .env.docker2 up，API_PORT仍为5001，不符合预期（期望为5002）
• 删除compose.yml中的env_file配置段后，运行docker compose --env-file .env.docker2 up，提示API_PORT未定义，不符合预期（期望为5002）

请问我哪里理解错了？

核心误区：两个env-file的作用完全不同 #

别搞混这两个配置的作用：

1. compose.yml里的env_file：只负责给容器内部加载环境变量，和Compose解析配置文件（比如ports里的$API_PORT占位符）没有关系。
2. docker compose --env-file：是给Compose工具本身提供变量，用来解析compose.yml里的占位符，但这些变量不会自动传入容器内部，必须手动配置关联。

你的场景问题拆解 #

1. 保留env_file执行--env-file .env.docker2时：
   容器内部的API_PORT还是5001，因为env_file: .env.docker1仍在生效，容器只会加载这个文件的变量；如果端口映射还是5001，大概率是主机环境中已经设置了API_PORT=5001，Compose会优先使用主机环境的变量。
2. 删除env_file后执行--env-file .env.docker2提示变量未定义：
   要么是.env.docker2文件格式错误（比如变量名后加了空格、引号），要么是主机环境中存在同名变量干扰，或者命令拼写有误。

两种解决方案 #

根据你的需求（通过--env-file切换端口映射和容器内部的API_PORT），任选一种即可：

方案1：让Compose变量与容器变量共用同一来源

修改compose.yml，去掉env_file，用environment将Compose解析到的变量传入容器：

volumes:
  app-data:

services:
  api:
    build: .
    restart: unless-stopped
    command: gunicorn ... 'main:app()'
    environment:
      - API_PORT=${API_PORT}
    ports:
      - "${API_PORT}:5000"

运行docker compose --env-file .env.docker2 up时：

• Compose会用.env.docker2里的API_PORT=5002解析端口映射
• 容器内部的API_PORT也会被设置为5002

方案2：通过变量指定容器要加载的env文件

修改compose.yml，将env_file的路径设为变量：

volumes:
  app-data:

services:
  api:
    build: .
    restart: unless-stopped
    command: gunicorn ... 'main:app()'
    env_file:
      - ${ENV_FILE:.env.docker1}
    ports:
      - "${API_PORT}:5000"

运行命令时手动指定要加载的env文件：

docker compose --env-file .env.docker2 -e ENV_FILE=.env.docker2 up

这样Compose会将env_file解析为.env.docker2，同时用该文件里的API_PORT=5002配置端口映射，容器内部也会加载这个文件的变量。

测试小技巧 #

运行docker compose --env-file .env.docker2 config可以查看Compose解析后的完整配置，快速确认端口映射、env文件路径是否正确，避免盲目排查。

内容的提问来源于stack exchange，提问作者Serge