结论：用 --build-arg 传参 + arg 声明 + env 显式转存是唯一可靠、可复现的多环境参数注入方式；arg 不跨阶段继承，必须每阶段重复声明，且不转为 env 则运行时不可见，敏感信息禁用 arg。
直接说结论：用 --build-arg 传参 + ARG 声明 + ENV 显式转存，是唯一可靠、可复现的多环境参数注入方式；不显式转成 ENV 的 ARG 在容器启动后就彻底消失。
ARG 声明位置与作用域必须严格匹配使用阶段
Dockerfile 中每个 FROM 都开启一个新构建阶段，ARG 不跨阶段自动继承。常见错误是只在开头声明一次，结果在第二阶段 RUN 里引用时报未定义。
- 多阶段构建中，每个阶段开头都得重新写
ARG，哪怕变量名和默认值完全一样 - 想在
FROM行里动态指定基础镜像（如FROM $BASE_IMAGE），ARG BASE_IMAGE=...必须写在该FROM之前，且不能在任何其他FROM后面再复用 - 若某阶段没用到某个
ARG，不声明也不会报错；但一旦用了却没声明，构建直接失败
构建时传参的三种方式及适用场景
命令行传参最直观，但 CI/CD 中易暴露敏感值；文件加载适合参数多且稳定；环境变量透传最常用，也最需注意 shell 展开和空格处理。
- 命令行单次构建：
docker build --build-arg ENV=staging --build-arg API_BASE=https://staging.api.com -t myapp:staging . - 从文件加载：
docker build $(cat .buildargs | xargs) -t myapp:prod .（注意.buildargs每行格式为KEY=VALUE，不能有空格或注释） - CI/CD 中透传（以 GitHub Actions 为例）：
--build-arg COMMIT_SHA=${{ github.sha }} --build-arg BUILD_TIME=$(date +%Y-%m-%d)，记得用run:步骤提前生成时间戳，避免语法错误
ARG 到 ENV 的转换不是可选项，而是必要操作
很多团队踩坑在于以为 ARG 声明后，应用就能在运行时读到它——实际根本读不到，除非你手动赋给 ENV。尤其前端项目依赖 REACT_APP_* 或后端读取 SPRING_PROFILES_ACTIVE 这类变量时，漏这步等于白配。
-
ARG NODE_ENV=production→ 必须跟一句ENV NODE_ENV=$NODE_ENV才能让 Node.js 应用感知 - 多阶段中，如果最终镜像需要某个参数（比如
VERSION），必须在最终阶段重新ARG并ENV，不能靠上一阶段 COPY 过来 - 不要试图用
RUN export VAR=$ARG，这种 shell 变量只在当前 RUN 层生效，不会进入镜像环境
敏感信息绝对禁止走 ARG 通道
ARG 值会明文留在镜像构建历史里，执行 docker history --no-trunc 镜像ID 就能直接看到所有传入的 --build-arg 值。密钥、token、数据库密码等必须换方式。
- 改用
docker buildx build --secret id=mykey,src=./secret.key ...配合RUN --mount=type=secret - 或通过挂载临时目录、配置中心拉取等方式在运行时注入
- CI/CD 中若已用
--build-arg传了敏感值，构建完立刻清理日志和缓存，否则等于裸奔
最容易被忽略的是多阶段构建中每个阶段的 ARG 独立性，以及 ARG 和 ENV 的生命周期混淆——前者只活在构建过程中，后者才进镜像。这两点出错，参数看似传进去了，实际运行时全失效。
