Docker Compose中env文件变量无法在service command中替换的问题

DevOps 小满

2026-8-4

Docker Compose环境变量未替换问题排查与解决

以下是导致你遇到的变量未替换、端口解析错误的常见原因及解决方法：

环境文件未正确加载
Docker Compose默认只会自动加载当前目录下的.env文件，如果你使用的是local.env，必须显式指定加载方式：
要么启动时加参数：docker-compose --env-file local.env up
要么在docker-compose.yml的migrate服务中配置：
```
services:
  migrate:
    env_file:
      - ./local.env
```
未正确加载环境文件的话，所有变量引用都会失效。
变量引用语法错误
你使用的$$POSTGRES_USER是Docker Compose中转义$的写法，最终会被解析成字面量$POSTGRES_USER，而非变量值。正确的变量引用语法是${VAR_NAME}，比如连接串应该写成：
```
services:
  migrate:
    command: migrate -database "postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/your_db?sslmode=disable" up
```
变量作用域未覆盖migrate服务
如果你的PostgreSQL变量只定义在postgres服务的environment字段里，migrate服务无法直接引用这些变量。需要确保migrate服务能访问到变量：要么将变量写入migrate加载的环境文件，要么在migrate服务中显式声明：
```
services:
  migrate:
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
```
端口错误的根源
当变量未被正确替换时，连接串会包含未解析的$POSTGRES_USER等字符串，数据库工具会将这些非法内容当成连接串的一部分，导致解析逻辑混乱，最终触发端口解析错误。解决变量替换问题后，该错误会自动消失。