ARG 是什么
ARG 声明只在构建期存在的变量，值由 docker build --build-arg 传入，没传就取默认值。它和 ENV 的关键差别是不写进运行环境，适合放版本号、内网源地址、编译开关这类构建参数。
基本信息
| 用途 | 构建期参数，不进入容器运行环境 |
|---|---|
| 语法 | ARG NAME[=默认值]，构建时 docker build --build-arg NAME=值 |
| 作用域 | 只在声明它的构建阶段内有效，跨阶段要各自声明 |
| 与 ENV 的差别 | ENV 会写进镜像配置并成为运行环境变量，ARG 不会 |
| 特殊位置 | 写在 FROM 之前的 ARG 供 FROM 行使用 |
典型使用场景
- 同一份 Dockerfile 构建不同版本：APP_VERSION 由 CI 传入，产物里的版本号与镜像标签保持一致
- 构建机在内网时传 MIRROR 与代理地址，公开代码里不留内部地址
- 用编译开关区分调试与生产：dev 带调试符号，prod 开裁剪
- 参数化基础镜像版本：ARG BASE=node:20-alpine 后接 FROM ${BASE}，一个文件适配多个版本
- 复现历史构建：把当时用到的 build-arg 值记进流水线日志，换机器也能复刻
示例
示例
# Dockerfile
ARG APP_VERSION=dev # 未传值时的默认值
ARG MIRROR=https://mirrors.example.com # 内网源地址
RUN printf 'version=%s\n' "$APP_VERSION" > /app/VERSION
# 构建命令
docker build --build-arg APP_VERSION=1.4.2 -t app/web:1.4.2 .
docker build --build-arg APP_VERSION --build-arg MIRROR . # 直接取当前环境变量ARG 与 ENV 对照
| 维度 | ARG | ENV |
|---|---|---|
| 存活范围 | 仅构建期 | 构建期与容器运行期 |
| 是否进镜像配置 | 不进镜像配置，但值会记入构建历史 | 写进镜像配置，docker inspect 可见 |
| 可否被覆盖 | 构建时用 --build-arg 覆盖 | 运行时用 docker run -e 覆盖 |
| 典型用途 | 版本号、镜像源、编译开关 | 应用配置、PATH、时区 |
| 缓存影响 | 值变化会让后续层缓存失效 | 同样影响缓存，但会成为运行环境 |
漏传值的 ARG 会静默取默认值，构建不会报错，脚本里忘了传参数就会产出看似正常的错误版本；CI 里最好显式断言版本号或摘要。
--build-arg 传的值会记录在镜像构建历史里，docker history 就能看到原文，任何口令、token 都不要走 ARG。