ARG实现构建时动态注入，核心是声明（FROM后设默认值）、传递（--build-arg或.buildargs）、使用（RUN/LABEL/ENV中引用）三步闭环；多阶段需各阶段重声明，不跨阶段继承。
通过 ARG 实现构建时变量动态注入，核心是让 Dockerfile 在不修改源码的前提下，根据传入的值改变构建行为。它不是运行时配置，而是构建阶段的“开关”和“输入”，关键在声明、传递、使用三步闭环。
在 Dockerfile 中正确定义 ARG
ARG 必须出现在 FROM 指令之后（若需用于 FROM，则必须在 FROM 之前声明），且建议全部设默认值，避免构建失败：
- 写法示例：ARG APP_ENV=production、ARG VERSION=0.1.0、ARG BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)
- 带默认值更健壮：未传参时自动回退，保障 CI 流水线稳定性
- 不要在 FROM 行后、RUN 前漏掉声明——否则 RUN 中引用会为空字符串
构建命令中用 --build-arg 注入值
docker build 支持三种主流传参方式，按场景选择：
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
- 单次构建：直接命令行传参，如 docker build --build-arg APP_ENV=staging --build-arg VERSION=2.3.0 -t myapp:staging .
- 批量配置：准备 .buildargs 文件（每行 KEY=VALUE），再用 $(cat .buildargs) 展开传入
- CI/CD 集成：GitHub Actions 中写 --build-arg COMMIT_SHA=${{ github.sha }}，GitLab CI 写 --build-arg CI_PIPELINE_ID=$CI_PIPELINE_ID
在构建阶段真正用起来
ARG 只是“可用”，不是“自动生效”。需显式用在 RUN、LABEL、ENV 等指令中：
- RUN npm ci --only=${APP_ENV} && npm run build（前端差异化依赖安装）
- LABEL org.opencontainers.image.version=${VERSION}（写入镜像元数据，便于 trace）
- ENV APP_ENV=$APP_ENV（若需运行时也访问该值，必须用 ENV 显式承接）
- Go 编译：RUN go build -ldflags "-X main.Version=${VERSION}" -o app .
多阶段构建中的 ARG 作用域管理
每个 FROM 开启新阶段，ARG 不跨阶段继承，必须重新声明：
- 第一阶段（构建器）：ARG NODE_VERSION=18 → FROM node:${NODE_VERSION}-alpine AS builder
- 第二阶段（运行时）：FROM ubuntu:22.04 → 必须再写一遍 ARG NODE_VERSION 才能在后续 RUN 中读取
- 若某阶段不需要该参数，可不声明；但一旦需要，就必须在该阶段开头明确定义
