BuildArg 是 Docker 构建时动态传参机制，需在 Dockerfile 中用 ARG 声明，仅限构建期使用；支持命令行、文件或 CI 变量传参，但不可用于敏感信息，且需显式转为 ENV 才能在运行时生效。
构建 Docker 镜像时，经常需要在不同环境（开发、测试、生产）中注入不同的配置，比如 API 地址、密钥前缀、构建时间戳等。单纯靠修改 Dockerfile 或硬编码显然不灵活。BuildArg 就是为此设计的机制——它允许你在 docker build 时动态传入变量，在构建阶段供 Dockerfile 使用（注意：仅限构建期，运行时不可见）。
BuildArg 的基本用法与声明
Dockerfile 中需显式用 ARG 声明参数名，才可在后续指令（如 RUN、ENV）中引用。声明顺序无关紧要，但若带默认值，必须写在 ARG 行末尾：
ARG BUILD_ENV=dev ARG APP_VERSION ARG COMMIT_SHA <h1>可在 RUN 中使用（注意：不能用于 FROM 后的 base image 名，除非是多阶段构建中的首个 ARG）</h1><p>RUN echo "Building for $BUILD_ENV, version $APP_VERSION" ENV ENVIRONMENT=$BUILD_ENV
未声明的 ARG 在构建时传入会被忽略；已声明但未传值且无默认值，则构建失败（除非使用 --no-cache 并确保上下文不依赖该变量）。
构建时传参的三种常用方式
-
命令行直接传参：
docker build --build-arg BUILD_ENV=prod --build-arg APP_VERSION=1.2.3 -t myapp:prod . -
从文件批量加载：创建
.buildargs（每行KEY=VALUE），然后用--build-arg配合cat或 shell 展开：$(cat .buildargs | xargs)（需注意空格和特殊字符） -
通过 CI/CD 环境变量透传：例如 GitHub Actions 中写成：
--build-arg COMMIT_SHA=${{ github.sha }}，GitLab CI 写成：--build-arg CI_COMMIT_TAG=$CI_COMMIT_TAG
常见陷阱与避坑建议
-
ARG 不是 ENV：ARG 值不会自动成为容器运行时环境变量，需显式
ENV VAR_NAME=$ARG_NAME才能保留到镜像中 -
FROM 指令前的 ARG 限制：只有在
FROM之前声明的 ARG 才可用于指定基础镜像名（如ARG BASE_IMAGE=alpine:3.18→FROM $BASE_IMAGE），之后声明的不行 -
多阶段构建中作用域隔离：每个
FROM开启新构建阶段，ARG 需在每个阶段内重新声明才能使用 -
敏感信息勿用 ARG 传递：ARG 值会留在镜像历史层中（可通过
docker history查看），密钥、token 等应改用docker buildx build --secret或挂载文件方式
结合 Makefile 或脚本实现参数化构建
为避免每次敲长命令，可封装构建逻辑。例如 Makefile 片段：
build-prod:
docker build \
--build-arg BUILD_ENV=prod \
--build-arg APP_VERSION=$(VERSION) \
--build-arg COMMIT_SHA=$(shell git rev-parse HEAD) \
-t myapp:$(VERSION)-prod \
.
<p>.PHONY: build-prod
执行 make VERSION=1.3.0 build-prod 即可自动注入版本和提交哈希。类似逻辑也可用 Bash 脚本或 CI 配置完成，核心是把动态值组织进 --build-arg 列表。
