Docker构建镜像报错无法识别构建参数invalid reference format怎么办

问题原因 #

你遗漏了在Dockerfile的FROM指令前声明VERSION构建参数。
Docker 对ARG参数的作用域有明确限制：如果需要在FROM指令中使用变量，必须在第一个FROM指令之前定义对应ARG。否则Docker解析FROM行时无法识别你传入的VERSION参数，会将$VERSION直接当作镜像标签的固定部分处理，最终触发镜像引用格式非法的报错。

解决方法 #

1. 调整Dockerfile开头内容，新增ARG声明：

# 先声明构建参数，才能在FROM行引用
ARG VERSION
FROM artifactory.company.com/local-docker-repo/dockerimage/docker-batch-base:$VERSION

2. 原有构建命令无需修改，直接执行即可正常识别传入的VERSION参数：

docker image build --build-arg VERSION=latest -q -t artifactory.company.com/local-docker-repo/batch/batch-run-sst:1.0-SNAPSHOT .

补充说明 #

如果是多阶段构建的场景，在FROM前声明的ARG属于全局作用域，不会自动带入后续构建阶段。如果后续阶段也需要用到VERSION参数，需要在对应阶段内重新声明一次ARG VERSION即可复用传入的参数值。

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