--build-arg 实现构建参数“声明+传递+使用”闭环，需先用 ARG 声明（支持默认值）、再通过 --build-arg 传值、最后在指令中用 ${VAR} 引用；ARG 不自动转为运行时环境变量，多阶段需每阶段重声明。
用 --build-arg 在构建阶段传入参数，核心是“声明 + 传递 + 使用”三步闭环。它不直接设置运行时环境变量，而是为构建过程提供临时、安全的可变值。
在 Dockerfile 中正确定义 ARG
必须先用 ARG 指令声明参数，才能被 --build-arg 接收。支持默认值，推荐始终设置，避免构建中断：
-
ARG APP_VERSION=1.0.0—— 有默认值，未传参时自动使用 -
ARG API_URL—— 无默认值，构建时必须用--build-arg API_URL=...显式传入，否则报错 - 参数名区分大小写，且不能包含空格或特殊字符（如
.、-），建议用下划线命名（BUILD_TIME） - 定义位置影响作用域：在
FROM之前定义的ARG，对所有构建阶段都可见；在FROM之后定义的，只在当前阶段有效
构建命令中用 --build-arg 传值
执行 docker build 时，通过 --build-arg 将实际值注入构建上下文：
- 语法：
docker build --build-arg KEY=VALUE ... - 可多次使用：
--build-arg APP_VERSION=2.3.1 --build-arg ENVIRONMENT=staging - 若参数值含空格或特殊字符，需用引号包裹：
--build-arg BUILD_INFO="v2.3.1-rc1 (2026-10-13)" - 未在 Dockerfile 中声明的参数名，Docker 会直接忽略（18.09+ 默认行为），不会报错；但建议保持严格匹配，避免隐性失效
在构建指令中引用 ARG 值
声明并传入后，可在 RUN、COPY（配合 --from）、FROM 等支持变量插值的指令中使用 ${VAR_NAME}：
-
FROM node:${NODE_VERSION}-alpine—— 用于动态选择基础镜像版本 RUN echo "Building for ${ENVIRONMENT}" > /app/env.logCOPY --from=builder /dist/${BUILD_PROFILE}/ ./public/- 注意：
ARG不会自动变成运行时环境变量。如需容器启动后也能读取，要显式转成ENV：ENV VERSION=${APP_VERSION}
多阶段构建中正确复用 ARG
每个构建阶段独立作用域，前一阶段的 ARG 不会自动延续到下一阶段：
- 必须在每个需要该参数的阶段开头重新声明：
ARG APP_VERSION - 不必重复传值 ——
--build-arg传入的值对整个构建过程全局有效，各阶段只要声明了同名ARG就能访问 - 常见写法示例：
FROM golang:${APP_VERSION} AS builder
ARG APP_VERSION
RUN echo "Builder uses ${APP_VERSION}"
FROM alpine:latest
ARG APP_VERSION
RUN echo "Final image built for ${APP_VERSION}"
