推送至Azure Container Registry的Docker镜像拉取时报no such file or directory错误

该错误本质是Windows容器镜像和拉取环境的文件系统/架构不兼容导致，具体触发原因有三类：

• 镜像架构标记错误：你的Windows容器镜像在构建或推送环节被错误标记为Linux架构，Linux节点拉取时会用overlayfs存储驱动解压Windows镜像的NTFS格式层，Windows系统特有的硬链接规则、大小写不敏感路径逻辑和Linux文件系统不兼容，进而触发层解压时的文件找不到报错。
• Windows版本不兼容：如果拉取镜像的节点是Windows节点，镜像使用的Windows内核版本（如Windows Server 2022/20H2）和节点的Windows系统版本不匹配，也会导致层解压失败。
• 构建工具自动跨架构转换：使用buildx这类跨架构构建工具时未指定和源镜像一致的平台参数，构建过程自动生成了不符合源镜像架构的额外层，破坏了原有镜像的文件结构。

• 先校验镜像元数据：执行docker manifest inspect <tagged image name>，对比该镜像和可正常拉取的源镜像的architecture、os.version字段是否完全一致，确认是否存在架构标记错误。
• 构建时强制指定平台参数：构建时添加和源镜像一致的平台标识，源镜像为Windows镜像时使用如下命令构建：

docker build --platform windows -t <tagged image name> .

如果需要匹配具体Windows版本，例如Windows Server 2022，可指定详细版本号：

docker build --platform windows/amd64/10.0.20348.0 -t <tagged image name> .

• 推送时避免多架构打包：执行docker push时不要添加--all-platforms参数，仅推送当前构建的单架构镜像即可。
• 校验拉取节点兼容性：如果在Windows节点上拉取镜像，确保节点的Windows系统版本和镜像的os.version字段匹配，跨版本的Windows容器镜像不支持直接运行。
• 强制复用源镜像层：构建时添加--pull=always参数，确保构建过程完全复用源镜像的所有层，不会生成额外的变更层。

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