# 

一个同步脚本跑了半年，一直很稳。它做一件很简单的事：上传完文件，拿服务端返回的 ETag 和本地算出来的 MD5 比一下，不一致就重传。

上个月开始报警，一天几十条「校验失败」。奇怪的是重传之后还是失败，但下载下来打开看，文件是好的，能正常解析。

问题不在文件，在 ETag 这个值本身。它被当成 MD5 用了半年，只是之前传的都是小文件，恰好没暴露。

## 为什么文档说 ETag「不一定」等于 MD5？

腾讯云对象存储的 MD5 校验文档，第一段就把这件事说明白了：

> COS 里每个对象对应一个 ETag，ETag 是对象被创建时对象内容的信息标识，但 ETag 不一定等同于对象内容的 MD5校验值，因此不能通过 ETag 来校验下载对象与原对象是否一致

这句话有两层。第一层是「不一定等同于 MD5」，第二层是「因此不能用来校验一致性」。第二层是结论，直接禁止了那个脚本的做法。

那正确的做法是什么，同一段接着写：

> 但用户可使用自定义对象元数据（x-cos-meta-*）来实现下载对象与原对象的一致性校验

再往下有两节，分别讲上传和下载两个方向的校验：

> 如果用户需要校验上传到 COS 的对象与本地对象是否一致，可以在上传时将 HTTP 请求的 Content-MD5 字段设置为经过 Base64 编码的对象内容 MD5 校验值，此时 COS 服务器将校验用户上传的对象，只有当 COS 服务器接收到的对象 MD5 校验值与用户设置的 Content-MD5 一致时，对象才可上传成功

以及下载侧：

> 如果用户需要校验下载对象与原对象是否一致，可在对象上传时使用校验算法计算对象的校验值，通过自定义元数据设置对象的校验值，在下载对象后，用户重新计算对象的校验值，并与该自定义元数据进行比较验证。在这种方式下，用户可自主选择校验算法

三句话，三个不同的机制，解决三个不同的问题。混用就会出现那个脚本的情况。

## 为什么 ETag 会「有时候像 MD5」？

因为在小文件、单次上传的场景下，很多实现的 ETag 恰好就是内容摘要。你传一个小文件，返回的 ETag 和本地 md5sum 一模一样，于是这条经验被记住了。

但这是观察，不是承诺。文档说的是「ETag 是对象内容的信息标识」——它承诺的是「内容变了 ETag 会变」，没有承诺「ETag 等于 MD5」。

一旦走分块上传，差异就出来了。分块上传的 ETag 不是对整体内容算一次摘要，而是对每个分块分别算摘要，再把这些摘要拼起来算一次。

结果就是两种形态：

| 上传方式 | ETag 的常见形态 | 能不能直接和 md5sum 比 |
| --- | --- | --- |
| 小文件、单次上传 | 32 位十六进制，看起来和 MD5 一样 | 常常能比上，但不能依赖 |
| 分块上传 | 一串十六进制后面跟着短横线和分块数 | 一定比不上 |
| 服务端加密或特殊存储类型 | 由服务端生成，与内容摘要无关 | 一定比不上 |

第二行那个「短横线加数字」的后缀，就是分块数的标记。看到这种形态还去和 32 位 MD5 比，永远不可能相等。

这里要说明一句：具体的生成算法，COS 文档没有承诺。所以不要记「ETag = 各块 MD5 拼接后再 MD5」，那只是一种实现方式。要记的是那个结论——**ETag 不是内容摘要的承诺，不能用来做完整性校验**。

## 三种校验手段，边界分别在哪？

把文档里的三种机制放在一起对比，选型就清楚了。

| 手段 | 校验发生在什么时候 | 能防住什么 | 代价 |
| --- | --- | --- | --- |
| Content-MD5 请求头 | 上传时，服务端比对 | 传输过程中数据损坏 | 上传前要先算一遍 MD5，大文件要读两遍 |
| 自定义元数据 x-cos-meta-* | 上传时写入，下载后自行比对 | 端到端的完整性 | 只能在写入时设置，事后补要复制对象 |
| ETag 比对 | 随时可读 | 只能判断「内容是否变化」 | 不能当摘要用 |

第二行的「只能在写入时设置」是个实际约束。如果对象已经传上去了，想补一个校验值，就得复制一次对象（复制时可以带新的元数据），也就是多一次读写。所以校验值要在第一次上传时就写进去。

## 上传侧怎么写才真的能防损坏？

最小可用的做法是带上 Content-MD5。它由服务端校验，不通过就直接拒绝上传，是最省心的一种。

```bash
# 先把 MD5 算出来，转成 base64，作为请求头带上
# macOS
MD5_B64=$(md5 -q ./bigfile.bin | xxd -r -p | base64)
# Linux
MD5_B64=$(openssl dgst -md5 -binary ./bigfile.bin | base64)

curl -X PUT "https://your-bucket.cos.ap-guangzhou.myqcloud.com/bigfile.bin" \
  -H "Content-MD5: ${MD5_B64}" \
  -H "Authorization: ${SIGNATURE}" \
  --data-binary @./bigfile.bin
```

这段的代价是读两遍文件：一遍算 MD5，一遍上传。对几十 GB 的文件，这个代价不小。

第二个做法更适合大文件：自己选一种摘要算法（比如 SHA-256，比 MD5 更抗碰撞），把结果写进自定义元数据。上传时带上，下载后再算一遍对比。

```bash
# 上传时写入自定义元数据，键名必须以 x-cos-meta- 开头
SHA256=$(sha256sum ./bigfile.bin | awk '{print $1}')

curl -X PUT "https://your-bucket.cos.ap-guangzhou.myqcloud.com/bigfile.bin" \
  -H "x-cos-meta-sha256: ${SHA256}" \
  -H "Authorization: ${SIGNATURE}" \
  --data-binary @./bigfile.bin

# 下载后核对
curl -s "https://your-bucket.cos.ap-guangzhou.myqcloud.com/bigfile.bin" -o ./downloaded.bin
curl -sI "https://your-bucket.cos.ap-guangzhou.myqcloud.com/bigfile.bin" \
  | grep -i 'x-cos-meta-sha256'
sha256sum ./downloaded.bin
```

这个方案的好处是算法可替换。等哪天 MD5 彻底不能用了，换成 SHA-256 只需要改一个键名和一个命令，不用动整个流程。

## 那个脚本该怎么改？

回到开头的问题。原脚本的逻辑是：上传 → 读 ETag → 和本地 MD5 比 → 不等就重传。

改法不是「换一个更宽松的比较」，而是「换一个能比的字段」。

第一，上传时把本地摘要写进自定义元数据。这一步是根上的改动，做完之后校验才有依据。

第二，校验时读自定义元数据，而不是 ETag。ETag 只在「判断对象有没有被改过」这个场景里有意义——比如缓存失效判断，两次读到的 ETag 不同就说明内容变了，这跟摘要无关。

第三，对历史对象做一次迁移。已经传上去的对象没有元数据，只能复制一次补上。数量大的话，用批量复制，别一个一个点。

| 原来的做法 | 问题 | 改法 |
| --- | --- | --- |
| ETag 和本地 MD5 比 | 分块上传一定不相等 | 改为读 x-cos-meta-* 里的摘要 |
| 不一致就重传 | 重传也还是不相等，形成循环 | 先定位是「真损坏」还是「不能比」 |
| 只校验上传成功 | 下载侧没有校验 | 下载后重算摘要再比 |

第二行值得单独说。那个脚本最消耗资源的地方不是校验，是「校验失败之后的重传」。因为它永远失败，所以每次同步都会把文件重传一遍，流量和请求数都翻倍。

## 什么时候 ETag 反而有用？

不是要否定 ETag。它的设计目的是「标识内容是否变化」，在这个用途上很称职。

比如做 CDN 缓存刷新判断：定时拉一次对象的 ETag，和上次记录的值比。不同就说明内容更新了，触发刷新。这个场景不需要知道内容是什么，只需要知道「变没变」。

再比如做增量同步：本地记录上次同步时的 ETag，下次先取 ETag 比对，相同就跳过下载。这能省掉大量流量。

这两个用法的共同点是：只做「相等/不相等」的判断，不做「内容摘要」的推断。一旦开始拿它算摘要、比长度、比格式，就已经用错了。

## 发布前该确认哪三件事？

| 检查项 | 具体动作 |
| --- | --- |
| 校验字段来源 | 代码里读的是 ETag 还是自定义元数据 |
| 校验算法是否统一 | 上传和下载用的是不是同一个算法、同一个键名 |
| 大文件是否走分块 | 走分块的对象，ETag 一定不能当摘要用 |

第一项在代码 review 时最容易发现，也最容易漏，因为 ETag 这个名字听起来就像一个校验值。

我把这类「名字看着像、语义其实不是」的字段整理成了一份对照表，比如 ETag 与 MD5、Content-Length 与对象实际大小、Last-Modified 与内容更新时间。表是用 AI墨衍 把散在几个仓库的笔记归拢成文档的，字段口径还是逐条对着官方文档核过。

顺便问一句：你们项目里用 ETag 做的那些判断，有哪几个其实是想要一个摘要？


一个同步脚本跑了半年，一直很稳。它做一件很简单的事：上传完文件，拿服务端返回的 ETag 和本地算出来的 MD5 比一下，不一致就重传。

ETag 不是 MD5：拿它校验下载文件，分块上传的对象一定对不上

编程语言

ETag不等于MD5，不能用于COS对象完整性校验。小文件单次上传时ETag可能恰好等于MD5，但分块上传会带分块数后缀，必然不相等。正确做法：上传时用Content-MD5请求头或自定义元数据x-cos-meta-*写入摘要，下载后重算比对。校验值须在首次上传时写入，事后需复制对象补设。

对象存储

代码解释

服务器

对象存储COS新用户低至1元！


CDN免费试用


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

ETag 不是 MD5：拿它校验下载文件，分块上传的对象一定对不上-腾讯云开发者社区-腾讯云

ETag 不是 MD5：拿它校验下载文件，分块上传的对象一定对不上

ETag 不是 MD5：拿它校验下载文件，分块上传的对象一定对不上

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐