Dockerfile ADD 使用 SHA-512 校验时报 digest mismatch

Dockerfile 用 ADD --checksum=sha512:... 下载 HTTPS 文件，构建却报 digest mismatch sha256:...: sha512:...。两端算法名不同，不能先把它当成“同一种校验算法发现文件被修改”：HTTP 来源的 ADD 校验目前只支持 SHA-256。

这个现象可能让人困惑，因为某些构建器会先接受 SHA-512 形式，直到实际下载、校验时才失败。能通过 Dockerfile 解析，不等于该算法受到 HTTP 下载实现支持。下面只讨论 HTTP/HTTPS 文件来源，不把 Git 来源的提交 SHA 校验混在一起。

先区分算法不支持与内容确实不符

看 Dockerfile 的完整指令和错误末行。如果请求的是 sha512:，实际比较的一侧却标为 sha256:，先修正校验方式。如果双方都已经是 sha256:，但摘要不同，则要继续核对下载 URL、版本、重定向目标及预期文件，不能用本文的算法限制解释所有 digest mismatch。

不要删除 --checksum 来让构建通过，也不要把错误消息中刚算出的值直接当成新的可信预期值。那只是本次收到内容的摘要；未经确认的错误页、替换文件或异常下载，同样能计算出一个 SHA-256。

可记录构建工具和 builder 信息，方便确认选项支持范围：

docker version
docker buildx version
docker buildx inspect

Dockerfile 前端从语法版本 1.6 提供 ADD 的 --checksum 选项。旧前端若提示未知选项，应先确认所用 builder 与 Dockerfile 语法版本；客户端版本号本身不能证明实际构建前端支持这个功能。

使用该文件可信的 SHA-256 摘要

SHA-512 和 SHA-256 是不同算法，不能只把前缀改成 sha256:，也不能截取 SHA-512 的前 64 个字符当作 SHA-256。应取得对应文件的 SHA-256 预期值，并确认它与目标版本、平台和发布资产一致。

下面是完整的 Dockerfile 结构示例。它使用固定 HTTP 来源与对应 SHA-256，展示如何把文件放进镜像；不是要求部署这个示例镜像：

# syntax=docker/dockerfile:1
FROM scratch
ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d \
    https://mirrors.edge.kernel.org/pub/linux/kernel/Historic/linux-0.01.tar.gz \
    /downloads/linux-0.01.tar.gz

实际项目要同时替换 URL、完整摘要和目标路径。不要保留示例摘要却换成自己的文件，也不要把一份包含文件名和摘要的清单整体粘进 --checksum。这里的参数只接收 sha256: 与该文件摘要的组合。

默认远程 ADD 把这个归档作为下载文件保存；校验通过不等于归档已解压，也不等于镜像里的软件已经安装。后续解包、安装及运行检查仍按原构建流程处理。

只有 SHA-512 发布值时，保留原来的验证要求

如果发布方只提供 SHA-512，不应为了适配 ADD 就放弃已有的可信校验。可以在受控的获取流程中，使用能验证 SHA-512 的工具核对下载内容；验证成功后，再计算这同一份已验证文件的 SHA-256，作为后续 ADD 的预期值。两次操作之间必须保证文件没有被替换，预期摘要也需要随版本受控保存。

另一条路径是在构建中沿用下载工具和 SHA-512 校验工具，只有校验成功才进入后续步骤。具体命令取决于构建镜像里已有的工具，不宜把主机上可用的命令直接假定为精简镜像中的内置功能。

无论选择哪条路径，单独下载文件并对它计算一个摘要，都不能证明它来自可信发布方。校验的是“下载内容是否等于已确认的预期内容”，不是仅证明工具能生成哈希。需要身份验证、签名验证或其他供应链约束的项目，应保留这些检查。

校验失败后不要用清缓存代替判断

--no-cache 可能让步骤重跑，但不会让 HTTP ADD 获得 SHA-512 支持；反复重试同一指令不会解决算法不匹配。完成修改后，应确认构建实际采用了新的 SHA-256 指令，所需下载步骤成功，镜像里目标文件和下游处理结果符合预期。

若仍报 SHA-256 摘要不符，停在下载验证阶段，保留错误和版本信息，再核对发布资产。不要绕过校验继续打包，也不要让应用更新流程使用尚未确认的文件。

修改前保留原 Dockerfile、可信校验材料和已经验收的镜像版本。新构建失败时继续使用原已验收镜像；回退构建配置不等于远程 URL 的内容也会退回，因此固定版本地址与可信摘要都需要保留。