跳到主要内容

docker compose 环境变量配置

docker compose up 会自动加载同目录下的 .env 文件。

但是，这里有一个非常容易踩坑的核心区别，你必须要注意：

默认情况下，自动加载的 .env 文件只作用于 docker-compose.yml 文件本身的变量替换，不会自动传递给容器内部运行的代码（如你的 Node.js 应用）。

为了让你彻底明白，请看以下两种场景：

场景一：用于 docker-compose.yml 内部的变量替换（自动生效）​

如果你的 .env 文件里有：

HOST_PORT=8018

在 docker-compose.yml 中，你可以直接使用 ${HOST_PORT}，Docker Compose 会自动读取 .env 并替换它：

services:
  api:
    image: my-api
    ports:
      - "${HOST_PORT}:8018" # 这里会自动变成 "8018:8018"

场景二：让容器内的代码读取到 .env（需要手动配置）​

如果你的 Node.js 代码里写了 process.env.ZY_API_KEY，并且这个 Key 写在同目录的 .env 文件里，容器内的代码默认是读不到的。

要让容器内的应用读取到环境变量，你必须在 docker-compose.yml 中显式地传递它们。有两种常用方法：

方法 A：使用 env_file（推荐，直接把整个文件传进容器）​

services:
  api:
    build: .
    ports:
      - "8018:8018"
    env_file:
      - .env  # 明确告诉 Docker 把这个文件里的所有变量注入到容器中

方法 B：使用 environment（按需传递）​

services:
  api:
    build: .
    ports:
      - "8018:8018"
    environment:
      - ZY_API_KEY=${ZY_API_KEY} # 左边是容器内的变量名，右边是读取宿主机 .env 的值
      - NODE_ENV=production

总结检查清单：​

  1. 确保 .env 文件和 docker-compose.yml 在同一个目录。
  2. 如果只是为了动态配置端口、镜像版本等，直接在 yml 里写 ${VAR_NAME} 即可。
  3. 如果是为了让你的 Node.js 代码（如 process.env.ZY_API_KEY）读到配置，务必在 docker-compose.yml 中加上 env_file: - .env。