容器镜像引用怎么写才对：registry、路径、tag 与 digest

很多团队的第一个坑不是 Kubernetes，而是：镜像名字写错。本文面向需要在配置文件（Compose、Helm、CI）里写镜像引用的同学，给出一套可检查的写法规范。

1. 镜像引用的基本结构

常见的直觉表达是：

registry / namespace / repository : tag

但在 Docker Hub 生态里，存在默认省略规则（例如默认 registry、以及 library 命名空间）。省略是为了省事，不是为了让新手更容易理解——这也是排查时最常见的混乱来源。

2. library 到底是什么

当你看到类似 nginx 这样的短名字时，它往往对应某个默认命名空间下的官方镜像（概念因 Registry 而异）。团队文档里建议：对公共教程里的短名字保持警惕，在正式环境中尽量写全，减少歧义。

3. tag：方便人类，digest：方便机器

• tag 适合交流与浏览（例如 1.2.3、alpine 变体）。
• digest（sha256） 更适合强调「不可变」：同 tag 也可能随重建而变化，digest 指向明确内容。

如果你的目标是可复现构建，应在流程里明确：何时允许 tag，何时必须 digest。

4. 多架构（multi-arch）与「你以为的 tag」

同一个 tag 可能解析出不同架构产物。部署到 arm 集群与 amd 集群时，「同名同 tag」也可能对应不同 manifest。出现架构不一致时，别急着怀疑业务代码，先核对 manifest。

5. 给团队的落地模板（建议写进规范）

• 开发环境：允许较宽松的 tag 策略，但要记录来源 Registry 与同步时间
• 预发 / 生产：优先 digest；至少冻结 minor 版本策略（按团队风险承受度）

6. 小结

镜像引用不是字符串拼接游戏：registry 归属、命名空间、仓库名、tag/digest 都是供应链的一部分。把引用写对，比事后排查 ImagePull 故障便宜得多。