ARG变量传递核心是“声明—传入—使用”三步闭环：在Dockerfile中用ARG声明（推荐设默认值，用于FROM的需置于其前）、构建时通过--build-arg或.buildargs文件传入、RUN/ENV中引用；多阶段需各阶段重声明，不跨阶段继承，敏感信息禁用ARG。
用 ARG 实现变量传递，核心是“声明—传入—使用”三步闭环。它不改变镜像运行时行为，但让一次 Dockerfile 适配多个构建场景成为可能。
正确声明 ARG 变量
在 Dockerfile 中用 ARG 指令定义参数，支持默认值，推荐始终设默认值以提升健壮性：
-
语法统一写成
ARG VAR_NAME=default_value，例如ARG NODE_VERSION=18或ARG BUILD_ENV=staging - 若需用于
FROM指令指定基础镜像（如FROM $BASE_IMAGE），必须把 ARG 声明放在 FROM 之前 - 多阶段构建中，每个
FROM后都是新阶段，前一阶段的 ARG 自动失效，需在新阶段重新声明
构建时传入参数的三种可靠方式
参数只有被显式传入才生效，Docker 不会自动读取环境变量或文件：
-
命令行逐个传参：最直观，适合调试或简单场景
docker build --build-arg BUILD_ENV=prod --build-arg APP_VERSION=2.1.0 -t myapp:prod . -
从文件批量加载：适合参数较多、CI/CD 流水线稳定运行
先创建.buildargs文件（每行KEY=VALUE，无空格）：BUILD_ENV=prod<br>APP_VERSION=2.1.0<br>COMMIT_SHA=abc123
再执行：docker build $(cat .buildargs | xargs) -t myapp:prod . -
CI/CD 环境变量透传：与平台深度集成，避免硬编码
GitHub Actions 示例：--build-arg COMMIT_SHA=${{ github.sha }} --build-arg CI_ENV=${{ env.ENV_NAME }}
GitLab CI 示例：--build-arg CI_COMMIT_TAG=$CI_COMMIT_TAG
在构建过程中安全使用 ARG 值
ARG 只存在于构建期，不能直接当运行时变量用，但可桥接到 ENV：
-
RUN 指令中可直接引用，例如：
RUN echo "Building for ${BUILD_ENV} environment" -
需要运行时可用？必须显式转成 ENV：
ARG BUILD_ENV=dev<br>ENV ENVIRONMENT=$BUILD_ENV
这样容器启动后printenv ENVIRONMENT才能输出值 -
敏感信息禁止用 ARG 传递（如 token、密码），因为
docker history可查到参数值；应改用buildx build --secret或挂载文件方式 - 未在 Dockerfile 中声明却传入的参数（如
--build-arg UNDEFINED=123），Docker 仅警告，不报错，但该值完全不可用
常见错误与规避要点
很多构建失败或行为异常，其实源于对作用域和生命周期理解偏差：
- FROM 后再声明 ARG，却想用于前面的 FROM → 报错或静默忽略；解决：所有用于基础镜像的 ARG 必须置于第一个 FROM 之上
- 多阶段构建中忘记重声明 ARG → 后续阶段无法访问，RUN 报变量未定义；解决：每个 FROM 后加对应 ARG 声明
-
误以为 ARG 传入即自动变成 ENV → 容器内
$VAR为空；解决：坚持用ENV TARGET_VAR=$SOURCE_ARG显式赋值 -
构建缓存干扰导致参数未生效 → 加
--no-cache强制重跑，或确保 RUN 指令实际依赖该 ARG（否则 Docker 可能跳过）
