Docker 构建镜像时报 repository name must be lowercase

构建还没完成，Docker 就拒绝了 -t 后面的镜像名：

invalid reference format: repository name must be lowercase

例如 registry.example.com/ExampleTeam/Web:RC1，需要修改的是仓库路径中的 ExampleTeam/Web。改成 registry.example.com/exampleteam/web:RC1 后，仓库路径符合小写要求；冒号后面的 RC1 是标签，可以包含大写字母，不必跟着转换。

先检查传给 Docker 的完整镜像引用。清理构建缓存、重新登录仓库或删除容器，都不会改变镜像名的语法。下面针对 Docker CLI 和现代 docker compose 的镜像命名，命令中的域名、项目目录和服务名均为示例。

仓库路径与标签不是同一段

常见镜像引用可以拆成：

registry.example.com:5000/exampleteam/web:RC1
└── 仓库服务地址和端口 ──┘ └── 仓库路径 ──┘ └标签┘

仓库路径由斜杠分隔的名称组成，其字母必须小写。标签使用另一套规则，允许大写字母、数字、下划线，也允许在首字符之后使用点和连字符；最长 128 个字符。标签不能以点或连字符开头。

因此，不能把整串引用无差别转成小写。把 :RC1 改成 :rc1 会改变目标标签；后续拉取或部署若仍使用原标签，就可能找不到预期镜像。也不要把注册表地址写成 https://registry.example.com/...，镜像引用中的仓库服务地址不带 URL 协议前缀。

若只有笼统的 invalid reference format，还可能是其他格式问题。这里的修复以已经确认仓库路径含大写字母为前提；路径小写之后仍失败，应继续核对实际传参，而不是反复改应用名称。

Compose 要检查合并和变量展开后的值

使用 Compose 时，查看与构建相同文件组合的镜像名：

docker compose -f compose.yaml -f compose.local.yaml config --images

没有覆盖文件就去掉第二个 -f。文件顺序、工作目录、项目名和环境变量应与原构建命令一致，否则看到的不是同一份配置。config --images 输出最终镜像名；完整 config 输出还可能包含敏感配置，不要直接粘贴到公开记录。

如果输出的仓库路径仍有大写，回到提供这个值的 image:、环境变量或覆盖文件修改。只改基础文件，而覆盖文件仍指定旧值，下一次构建仍会使用旧名。配置解析也可能直接拒绝非法引用；此时根据错误定位相应服务，检查它的 image: 及变量来源。

以下是已有 Dockerfile 项目的最小示例，只展示构建目录与镜像名之间的关系：

services:
  app:
    build:
      context: .
    image: registry.example.com/exampleteam/web:RC1

把这些字段合并进原服务，保留原有 Dockerfile、构建参数、挂载、端口和环境设置，不要用这几行覆盖整个项目配置。context: . 要对应实际构建目录；目录名可以有自己的大小写，不能因为镜像仓库名需要小写，就批量重命名源码目录。

同时配置 build: 和 image: 时，Compose 用指定的镜像名给构建结果打标签。未写 image: 时，默认名称来自项目和服务；应以解析后的结果为准。若需保留服务名称及其引用关系，可以显式填写有效的 image:，但部署和推送流程也要同步使用这个名字。

用新标签验证，保留原有镜像

直接使用 Docker CLI 构建时，修正 -t 参数即可。下面假设当前目录已有经过核对的 Dockerfile，目标标签尚未用于现有发布：

docker build -t registry.example.com/exampleteam/web:RC1 .
docker image inspect registry.example.com/exampleteam/web:RC1 \
  --format '{{.Id}} {{json .RepoTags}}'

在测试构建环境运行，并保留原有、仍在使用的镜像标签或镜像 ID。构建会执行 Dockerfile、消耗磁盘和网络资源；不要为了检查一个名称就在生产环境运行未知构建过程。重复使用已有标签还可能让它指向新的构建结果，应先确认没有覆盖当前发布所依赖的标签。

Compose 项目则使用原文件组合构建目标服务，例如 docker compose -f compose.yaml -f compose.local.yaml build app。普通构建不会替你完成应用部署；也不要为了此次命名修复顺手增加 --push，把测试产物上传到仓库。

如果本地已经有需要的镜像内容，只是要给它加一个合法的新名字，可以使用 docker image tag，不必重新构建：

docker image tag existing-app:known-good \
  registry.example.com/exampleteam/web:RC1

existing-app:known-good 必须替换成已确认的本地镜像引用或 ID，目标应是未占用的新标签。这条命令创建指向原镜像的新引用，不会把镜像推送到远端，也不会自动重建运行中的容器。

格式通过后还要核对发布引用

构建成功后，检查 docker image inspect 中的 ID 和标签，并确认后续 Compose 配置、CI 推送目标和部署配置使用相同的仓库路径与标签。格式合法并不证明远端仓库存在、账号有推送权限，或远端已经有这个标签。

若修正名称后出现认证失败、仓库不存在或标签不存在，按新的错误检查对应环节，不要把它们继续归因于大小写解析。旧版 docker-compose 的错误包装也可能不同；不能把所有“无法连接 Docker daemon”都解释成镜像名大写。

改名期间保留可用的旧镜像引用与原配置。需要回退时恢复此前可用的配置和镜像；如果同名标签已被新构建覆盖，应使用提前保留的引用或 ID，不能仅靠把 Compose 文本改回去找回旧镜像。完成验证前无需执行镜像清理或删除数据卷。