环境变量必须在Docker镜像构建阶段用ENV指令提前定义并固化到镜像层，才能被RUN、CMD等后续指令及容器运行时正确使用；ARG可用于构建时传参，再通过ENV转为持久变量；敏感信息禁止写入ENV，应通过--secret、-e或配置文件等方式动态注入。

环境变量在容器镜像中必须在构建阶段就写入，才能被后续的 RUN、CMD、ENTRYPOINT 等指令正确识别和使用。关键在于：变量要“提前定义”，且不能依赖运行时才注入的宿主机环境（除非显式传递）。

用 ENV 指令声明并固化到镜像层

ENV 是最直接、最可靠的方式。它会在镜像中持久写入环境变量，所有后续层都能读取，且容器启动后依然生效。

• 语法简单明确：ENV KEY=value 或 ENV KEY="value with space"
• 变量名不加 $，赋值内容可含空格、引号，推荐用等号分隔
• 多个变量建议分行写，提升可读性和调试性
• 示例：

ENV NODE_ENV=production
ENV JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
ENV PATH=$JAVA_HOME/bin:$PATH

注意：PATH 这类系统变量需用 $ 符号引用已有值，Docker 构建器会自动展开。

避免在 RUN 中用 shell export 临时设置

下面写法是无效的：

RUN export APP_VERSION=1.2.0 && echo $APP_VERSION

因为 export 只在当前 shell 进程有效，该 RUN 指令执行完后层即提交，变量随即丢失。后续指令无法读取 APP_VERSION。

正确做法是先 ENV，再 RUN：

Soundful

Soundful是一款通过曲风模板快速生成原创免版税音乐的 AI 音乐平台。

下载

ENV APP_VERSION=1.2.0
RUN echo "Building v$APP_VERSION" && ./build.sh

需要动态值？用构建参数 ARG + ENV 组合

如果变量值需在 docker build 时传入（如版本号、分支名），不能硬编码，就用 ARG 定义参数，再用 ENV 转为镜像环境变量：

ARG BUILD_VERSION
ENV VERSION=$BUILD_VERSION

构建时传参：

docker build --build-arg BUILD_VERSION=2.1.0 -t myapp .

⚠️ 注意：ARG 默认只在构建期可见，不进入最终镜像；必须显式用 ENV 赋值，才能让容器运行时也拿到。

敏感信息不要写进 ENV（如密码、密钥）

ENV 写入的变量会保留在镜像层中，执行 docker history 或 docker inspect 可能暴露明文。应改用以下方式：

• 构建时通过 --secret（配合 Docker BuildKit）传入
• 运行时通过 -e 或 --env-file 注入
• 挂载文件或 ConfigMap（K8s 场景）

例如，数据库密码不应出现在 Dockerfile 中：

# ❌ 危险！
ENV DB_PASSWORD=abc123
<h1>✅ 推荐：运行时注入</h1><p>docker run -e DB_PASSWORD=abc123 myapp
</p>