Docker Compose无法读取.env.dev文件的问题排查求助

问题描述 #

使用dockerize配置Strapi项目的Dockerfile与Compose文件，将通用配置写入.env，敏感信息与开发环境配置写入.env.dev。执行docker compose build时出现大量变量未设置的警告，只有添加--env-file .env.dev参数执行docker compose --env-file .env.dev build时警告才会消失。

核心原因 #

1. Compose变量解析时机差异：Compose文件中的变量替换（如${DATABASE_PASSWORD}、${ADMINER_PORT}）是在Compose解析配置文件的阶段完成的，这个阶段只会读取Compose进程自身的环境变量；而services下的env_file配置是容器启动时才会加载的，对解析阶段的变量替换完全无效。
2. 默认env文件规则限制：Docker Compose默认只会自动加载当前目录下的.env文件，不会识别.env.dev这类自定义命名的环境文件。直接执行docker compose build时，Compose只能读到.env里的HOST和PORT，.env.dev里的变量都无法被解析阶段读取。

解决方案 #

方案1：让Compose默认加载.env.dev #

可以通过两种方式让Compose自动读取.env.dev：

• 方式A：设置环境变量
  在执行命令前设置临时环境变量，或者写入shell配置文件（如~/.bashrc、~/.zshrc）实现永久生效：

  export COMPOSE_ENV_FILE=.env.dev
  

  之后直接执行docker compose build即可正常加载变量。
• 方式B：添加顶层env_file配置
  在docker-compose-dev.yaml的最顶层（与services同级）添加：

  env_file:
    - .env.dev
  

  这样Compose解析配置时会先加载这个文件里的变量，还会覆盖默认.env中的同名变量（比如.env.dev里的PORT会覆盖.env的1337）。

方案2：优化变量使用逻辑 #

• 容器内需要的环境变量，直接通过env_file加载即可，无需在environment字段重复引用变量（比如DATABASE_CLIENT: ${DATABASE_CLIENT}完全多余，env_file已经会把.env.dev里的DATABASE_CLIENT注入容器）。
• 对于需要在Compose解析阶段使用的变量（比如ports里的${ADMINER_PORT}、Dockerfile里的EXPOSE ${PORT}），必须确保Compose能在解析时读到这些变量：要么通过上述方案加载.env.dev，要么在构建时显式传递参数，比如传递PORT给Docker Build：

  docker compose build --build-arg PORT=$(grep PORT .env.dev | cut -d= -f2)
  

方案3：规范多环境命名（可选） #

如果要区分多环境，可以给Compose文件命名为docker-compose.dev.yaml，搭配.env.dev使用，执行命令时：

docker compose -f docker-compose.dev.yaml --env-file .env.dev build

这种方式更清晰，适合后续扩展生产环境配置。

额外注意点 #

Dockerfile中的EXPOSE ${PORT}属于构建阶段的变量引用，Docker Build本身不会读取Compose的环境文件，需要在Compose的build字段里添加args传递变量：

build:
  context: .
  dockerfile: dev.Dockerfile
  args:
    PORT: ${PORT}

这样构建时就能正确传递PORT变量给Dockerfile。

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