Dockerfile ARG 是什么
ARG 声明只在构建期存在的变量，通过 docker build --build-arg 传入，也可以给默认值。它适合镜像源、版本号、构建标识这类随环境变化的参数。两个要点：多阶段构建里每个阶段都要重新声明，声明之前的指令无法引用；ARG 的值会出现在构建历史与失败日志中，所以不能用它传递密码或令牌，敏感数据应改用 BuildKit 的 secret 挂载机制。
基本信息
| 语法 | ARG NAME[=默认值]，配合 docker build --build-arg NAME=值 |
|---|---|
| 作用域 | 从声明处到该构建阶段结束；多阶段构建每个阶段需重新声明 |
| 与 ENV 关系 | ARG 仅构建期有效；ENV 持久进入镜像，可被 ARG 赋值 |
| 安全边界 | 值可从构建历史读出，敏感数据使用 BuildKit --secret |
| 内置参数 | 代理类参数需要先在 Dockerfile 中声明才会被构建命令采用 |
典型使用场景
- 切换包管理镜像源：内网环境与公网环境使用不同的源地址
- 注入构建版本号与提交号，让程序内部能打印出准确的版本信息
- 多阶段构建中传递产物路径或编译开关，同一份文件支持不同构建形态
- 为不同目标架构传递平台相关参数，配合 buildx 构建多架构镜像
- CI 流水线把分支或构建编号作为参数写入镜像标识，便于追溯来源
镜像源参数示例
镜像源参数示例
# Dockerfile
ARG NPM_REGISTRY=https://registry.npmmirror.com
RUN npm config set registry "$NPM_REGISTRY"
# 构建时覆盖
docker build --build-arg NPM_REGISTRY=https://registry.npmjs.org -t app:dev .多阶段重新声明
多阶段重新声明
FROM node:20 AS build
ARG BUILD_VERSION=0.0.0 # 第一阶段声明
RUN echo $BUILD_VERSION > /tmp/version
FROM nginx:1.27
ARG BUILD_VERSION # 新阶段必须重新声明才能引用，取值仍来自 --build-arg
RUN echo $BUILD_VERSION > /usr/share/nginx/html/version.txtARG 与 ENV 对照
| 维度 | ARG | ENV |
|---|---|---|
| 生效阶段 | 仅构建期 | 构建期与运行期 |
| 是否进镜像配置 | 不进运行环境，但值可见于构建历史 | 保存在镜像配置中 |
| 运行时传入 | 不支持 | docker run -e 可覆盖 |
| 典型用途 | 镜像源、版本号、构建标识 | 时区、字符集、应用目录 |
| 敏感值 | 不可用，改用 secret 机制 | 不可用 |
构建失败信息里会回显 ARG 的值：CI 日志中带令牌的构建参数会连同报错一起泄露，敏感数据必须改用 secret 挂载方式传入。
内置构建参数（例如代理相关变量）需要先在 Dockerfile 中用 ARG 声明才会被采用；未声明时即使构建命令传了参数，也不会影响构建过程。