无法将机密环境变量传递至Dockerfile的问题排查

我创建了docker-compose.yml、Dockerfile及.env文件来调试问题：

.env 文件 #

DATABASE_URL="postgresql://postgre...."

docker-compose.yml 文件 #

services:
  web:
    build: .
    ports:
      - '8080:8000'
    env_file:
      - .env
    entrypoint: echo "Hush! This is a secret '$DATABASE_URL'"

Dockerfile 文件 #

ARG PYTHON_VERSION=3.10-slim-bullseye

FROM python:${PYTHON_VERSION}
ENV DATABASE_URL=$DATABASE_URL
RUN echo DATABASE_URL:  ${DATABASE_URL}

执行docker compose up时，构建阶段的RUN指令未输出DATABASE_URL，但容器启动后的entrypoint能正常输出该机密变量；docker compose config显示环境变量已配置，请问为何Dockerfile无法获取该变量？

Docker的构建阶段与容器运行阶段是完全独立的两个流程：

• env_file配置的环境变量仅在容器启动时注入到容器实例中，不会传递到镜像构建过程。
• Dockerfile中ENV DATABASE_URL=$DATABASE_URL里的$DATABASE_URL在构建时无有效值，因为构建阶段未接收到该变量，因此RUN指令输出为空。
• 容器启动时，Compose会将env_file中的变量注入容器环境，所以entrypoint能正常读取到变量值。

若需在构建阶段使用该变量，可采用以下两种常用方式：

方式1：通过构建参数传递变量 #

修改docker-compose.yml，在build块中添加args传递变量：

services:
  web:
    build:
      context: .
      args:
        - DATABASE_URL=${DATABASE_URL}  # 从.env读取后传递至构建阶段
    ports:
      - '8080:8000'
    env_file:
      - .env
    entrypoint: echo "Hush! This is a secret '$DATABASE_URL'"

同时修改Dockerfile，先声明ARG接收构建参数：

ARG PYTHON_VERSION=3.10-slim-bullseye
ARG DATABASE_URL  # 声明接收构建参数

FROM python:${PYTHON_VERSION}
ENV DATABASE_URL=$DATABASE_URL
RUN echo DATABASE_URL:  ${DATABASE_URL}

方式2：在构建块中直接设置环境变量 #

在docker-compose.yml的build块中使用environment配置构建阶段的环境变量：

services:
  web:
    build:
      context: .
      environment:
        - DATABASE_URL=${DATABASE_URL}
    ports:
      - '8080:8000'
    env_file:
      - .env
    entrypoint: echo "Hush! This is a secret '$DATABASE_URL'"

此方式下Dockerfile无需额外声明ARG，可直接使用环境变量：

ARG PYTHON_VERSION=3.10-slim-bullseye

FROM python:${PYTHON_VERSION}
ENV DATABASE_URL=$DATABASE_URL
RUN echo DATABASE_URL:  ${DATABASE_URL}

注意：若DATABASE_URL为敏感信息，不建议在构建阶段传递——构建参数会被保留在镜像历史记录中，存在泄露风险。这种情况下应仅在容器运行阶段使用该变量，即保持你原本的配置方式，构建阶段避免依赖敏感变量。

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