Dockerfile多阶段构建中ARG在FROM内未正确设置的问题

你的问题核心是Docker多阶段构建中ARG变量的作用域限制：

每个FROM指令会启动一个独立的构建阶段，前一个阶段内定义的ARG变量不会自动延续到后续阶段。你将ARG VERSION="latest"写在第一个FROM之后，这个变量仅属于first-stage阶段，第二个second-stage阶段无法读取它，导致${VERSION}被解析为空字符串，最终镜像引用变成docker.io/library/hello-world:，触发"镜像引用格式无效"的错误。

两种可行的修复方案： #

1. 全局定义ARG（推荐）

将ARG声明放在所有FROM指令之前，这样所有构建阶段都能访问该变量：

ARG VERSION="latest"

FROM docker.io/library/alpine as first-stage
RUN echo "test"

FROM docker.io/library/hello-world:${VERSION} as second-stage

2. 在目标阶段重新声明ARG

如果不想全局共享变量，可以在第二个阶段重新声明ARG（可指定默认值）：

FROM docker.io/library/alpine as first-stage
RUN echo "test"

FROM docker.io/library/hello-world:${VERSION} as second-stage
# 重新声明ARG，当前阶段才能使用该变量
ARG VERSION="latest"

修改后执行原构建命令即可正常完成构建：

docker build \
    --tag=img-name-dev:latest \
    .

内容的提问来源于stack exchange，提问作者brunston