核心是将环境差异点抽象为构建时变量：在Dockerfile中用ARG声明并设默认值，多阶段需各阶段重声明；构建时通过--build-arg传参，敏感信息禁用，运行时需用ENV显式转换。
用 ARG 实现不同环境的动态配置，核心是把环境差异点抽象成构建时变量，在 Dockerfile 中声明、引用，并在构建命令中按需传入具体值。它不改变镜像结构，只控制构建行为和最终注入的运行时信息。
明确哪些配置适合用 ARG 控制
优先选择那些只影响构建过程或需要写入最终镜像但不涉密的值，比如：
- 前端项目的 API 地址（REACT_APP_API_URL）
- 后端激活的 Spring Profile（PROFILE）
- 应用版本号（APP_VERSION）
- 构建时间戳或 Git 提交哈希（BUILD_TIME、COMMIT_SHA）
- 是否启用调试模式（DEBUG_MODE=true）
Dockerfile 中正确声明与使用 ARG
ARG 必须显式声明才能使用，且作用域仅限当前阶段。多阶段构建中每个 FROM 后都要重新声明：
- 在 FROM 前声明的 ARG 可用于指定基础镜像名（如 ARG BASE_IMAGE=nginx:alpine → FROM $BASE_IMAGE）
- 在 FROM 后声明的 ARG 不能用于前面的 FROM，但可用于 RUN、COPY、ENV 等后续指令
- 若需运行时也能读取该值，必须用 ENV VAR_NAME=$ARG_NAME 显式转换
- 为防构建失败，建议给关键 ARG 设置默认值：ARG ENV_TYPE=dev
构建时按环境传参的实用方式
根据使用场景选择最顺手的方式：
-
本地快速验证：直接命令行传参
docker build --build-arg ENV_TYPE=prod --build-arg API_URL=https://api.prod.com -t myapp:prod . -
团队统一配置：用 .buildargs 文件管理常用组合
文件内容：ENV_TYPE=staging<br>API_URL=https://api.staging.com
执行：docker build $(cat .buildargs | xargs -n 1 echo --build-arg) -t myapp:staging . -
CI/CD 自动化：绑定平台变量
GitHub Actions：--build-arg COMMIT_SHA=${{ github.sha }}
GitLab CI：--build-arg CI_ENV=$CI_ENVIRONMENT_NAME
避免常见误用导致配置失效
很多“参数没生效”问题其实出在细节上：
- 未在 Dockerfile 中 先 ARG 声明，就直接在 RUN 中用
$VAR—— 构建会报错或静默忽略 - 多阶段构建中，第二阶段忘记 重新 ARG XXX，导致变量为空
- 把敏感信息（如密钥、token）通过 --build-arg 传入 —— 这些值会留在镜像历史里，可用
docker history 镜像名查看 - 混淆 ARG 和 ENV：只写了 ARG API_URL，但没写 ENV REACT_APP_API_URL=$API_URL，结果运行时程序读不到
