Dockerfile 中 ARG 必须在 FROM 前声明才能用于动态基础镜像；多阶段构建可为各阶段独立定义 ARG；构建时用 --build-arg 覆盖默认值，但 ARG 仅构建期生效且不参与运行环境。
在 Dockerfile 中，FROM 指令本身不支持直接使用 ARG 定义的变量（尤其在多阶段构建中），但可以通过合理设计实现“动态基础镜像”效果——关键在于 ARG 必须在 FROM 之前声明，且需配合构建时传参。
ARG 必须在 FROM 之前声明
Docker 构建器要求所有用于 FROM 的 ARG 必须在该 FROM 指令前定义，否则会报错 ARG before FROM is not supported。这是硬性语法限制。
- ✅ 正确写法：
ARG BASE_IMAGE=python:3.11-slim FROM $BASE_IMAGE ...
- ❌ 错误写法（ARG 在 FROM 后）：
FROM python:3.11-slim ARG BASE_IMAGE # 无效：无法影响当前 FROM，且可能被忽略
支持多阶段构建中的独立 ARG
每个构建阶段可定义自己的 ARG，并用于本阶段的 FROM。不同阶段可引用不同镜像，提升灵活性。
- 例如构建前端 + 后端混合项目：
ARG FRONTEND_BASE=nginx:1.25-alpine ARG BACKEND_BASE=python:3.11-slim <p>FROM $FRONTEND_BASE as frontend-builder WORKDIR /app COPY package*.json ./ RUN npm ci --only=production</p><p>FROM $BACKEND_BASE as backend-builder WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt</p><p>FROM $FRONTEND_BASE COPY --from=frontend-builder /app/dist /usr/share/nginx/html COPY --from=backend-builder /app /app CMD ["gunicorn", "app:app"]
构建时传参覆盖默认值
使用 docker build --build-arg 可覆盖 Dockerfile 中 ARG 的默认值，从而切换基础镜像。
- 命令示例：
docker build \ --build-arg BASE_IMAGE=python:3.10-slim \ -t myapp:py310 .
- 注意点：
- 未传参时自动使用
ARG BASE_IMAGE=xxx中的默认值 - 多个
--build-arg可同时指定，如--build-arg A=1 --build-arg B=2 - 敏感信息（如私有仓库凭证）不应通过
ARG传入FROM，建议用DOCKER_BUILDKIT=1配合RUN --mount=type=secret
常见陷阱与规避方式
实际使用中容易踩坑，需特别注意作用域和缓存行为。
-
ARG 不是 ENV：它只在构建期生效，不会注入容器运行环境；若需运行时可用，需额外
ENV赋值 - FROM 后的 ARG 不影响当前阶段镜像：仅对后续指令（如 RUN、COPY）有效
-
缓存失效风险：一旦
BASE_IMAGE改变，整个构建链从该FROM开始全部重建（Docker 缓存失效） -
私有镜像认证：若
FROM引用私有 registry（如myreg.example.com/app/base:1.0），确保构建机已登录：docker login myreg.example.com
