Docker Compose无法读取.env.dev文件致环境变量未设置的解决

问题场景 #

项目目录结构：

/backend
  .env.dev
  docker-compose-dev.yml
  /project

在/backend目录下执行命令：

docker-compose -f docker-compose-dev.yml up --build

出现以下警告：

WARNING: The DB_USER variable is not set. Defaulting to a blank string.
WARNING: The DB_PASSWORD variable is not set. Defaulting to a blank string.
WARNING: The DB_NAME variable is not set. Defaulting to a blank string.

已在docker-compose-dev.yml中为django和db服务配置env_file: ./.env.dev，且.env.dev内容正确：

DB_NAME=db_dev
DB_USER=postgres
DB_PASSWORD=passsss132132
ENV_TYPE=DEV

为什么--env-file参数能解决问题 #

Docker Compose读取环境变量分两种完全独立的逻辑：

1. 服务容器内部变量：通过服务级的env_file配置，是给容器启动后内部进程（比如Django、PostgreSQL）使用的，和Docker Compose解析配置文件的过程无关。
2. Compose解析配置时的变量：如果你的docker-compose-dev.yml里用了${DB_USER}、${DB_NAME}这类占位符（比如配置数据库连接地址、服务环境变量），这些变量默认从终端环境或当前目录下的.env文件读取。

你遇到的警告，是Compose在解析配置文件时找不到这些占位符对应的变量，所以抛出警告并默认设为空字符串。而--env-file=.env.dev参数是直接告诉Compose：解析配置文件时就从这个文件里读变量，占位符能被正确替换，自然就没有警告了。

规范解决方式 #

根据你的场景，有三种常用的规范处理方案：

方案1：重命名.env.dev为.env（推荐）

Docker Compose默认会自动加载当前目录下的.env文件作为解析配置的变量源。把.env.dev改名为.env后，直接执行：

docker-compose -f docker-compose-dev.yml up --build

就能正常运行，不需要额外参数。

如果要区分多环境（dev/prod/test），可以保留.env.dev，通过脚本或命令快速切换：

# 开发环境下切换
cp .env.dev .env
docker-compose -f docker-compose-dev.yml up --build

方案2：在docker-compose-dev.yml中添加顶级env_file字段

从Docker Compose 1.28版本开始，支持在配置文件的顶级位置添加env_file字段，专门指定Compose解析配置时用的环境文件：

# docker-compose-dev.yml
version: '3.8'
# 顶级字段：告诉Compose解析配置时读取这个文件的变量
env_file: ./.env.dev
services:
  django:
    # 服务级字段：给容器内部进程提供变量
    env_file: ./.env.dev
    # 其他服务配置...
  db:
    env_file: ./.env.dev
    # 其他服务配置...

这样配置后，直接执行原命令就能让Compose自动读取.env.dev，同时容器内部也能拿到变量，一举两得。

方案3：用脚本封装命令

如果不想修改文件，也可以把长命令封装到Makefile或shell脚本里，避免每次手动输入：

# Makefile
dev-up:
	docker-compose -f docker-compose-dev.yml --env-file=.env.dev up --build

执行时只需输入make dev-up即可。

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