Go 浏览器上传大文件怎么分片：Range、校验和与断点恢复的接口边界

浏览器上传一个 2GB 视频或安装包时，直接把文件塞进一次 POST，最先撞上的通常不是 Go 的磁盘速度，而是连接中断、代理体积限制和重试成本。更稳的做法是让浏览器把文件切成固定大小的分片，每个分片带上编号、字节范围和校验信息，Go 服务端先落盘并确认，再由一个明确的合并动作生成最终文件。

浏览器为什么要同时提交编号和字节范围

假设前端把文件切成每片 8 MiB，最后一片可能不足这个大小。第 7 片不只是“数组下标 6”，它还应该声明自己覆盖的字节区间。推荐使用这样的请求头：

POST /api/uploads/u_9f3/chunks/6
Content-Range: bytes 50331648-58720255/734003200
X-Chunk-SHA256: 9f0c...c8a1
Content-Length: 8388608

编号负责表达逻辑顺序，范围负责表达物理位置，总长度帮助服务端判断任务是否被换成了另一份文件。服务端不要相信任何一个字段的单独声明：编号、起止字节、请求体长度和任务元数据应互相核对。

Go 服务端的最小分片模型

一个上传任务至少需要稳定的任务 ID、文件总长度、分片大小、总片数和已完成集合。文件名只适合展示，不能作为任务主键；同名文件同时上传会把临时目录搅在一起。

type UploadMeta struct {
    ID          string
    TotalSize   int64
    ChunkSize   int64
    TotalChunks int
    FileSHA256  string
}

type ChunkReceipt struct {
    Index  int
    Start  int64
    End    int64
    Size   int64
    SHA256 string
}

落盘路径可以按 uploads//chunks/000006.part 组织。先写到同目录的临时文件，再调用 os.Rename，目录扫描只把带有最终后缀的文件计入已完成集合。这样服务进程在写入中途崩溃时，不会把半个分片误判成成功。

处理一个分片时，先过四道边界检查

第一道：任务和编号

确认任务存在、状态仍是 uploading，并且 0 。任务已经合并或过期时，应返回明确的业务状态，让浏览器重新查询，而不是继续写入最终文件。

第二道：范围和长度

服务端根据编号推导期望起点和终点，最后一片单独处理。解析 Content-Range 后，必须验证 end-start+1 等于实际读取到的字节数；不能为了兼容客户端而把多出的字节静默截掉。

第三道：校验和

把请求体流式写入临时文件的同时计算 SHA-256。头部校验值不匹配时删除临时文件并返回失败，匹配时才保留分片回执。这里的分片哈希用于传输完整性，整文件哈希用于最终内容验收，作用不同。

第四道：重复请求

如果目标分片已经存在，先读取它的回执。编号、范围、大小和 SHA 全部一致时直接返回幂等成功；只要有一项不同，就删除旧回执并要求客户端重新上传，避免“同一个编号对应两种内容”。

断点恢复应该查询什么，而不是猜什么

浏览器重启后不要只保存一个“已上传到第几片”的数字，因为并发上传和单片重试会让中间出现空洞。服务端提供一个轻量查询接口，返回已确认的分片编号、每片 SHA 和任务版本：

GET /api/uploads/u_9f3/status

{
  "upload_id": "u_9f3",
  "total_chunks": 88,
  "received": [0, 1, 2, 4, 5],
  "file_sha256": "pending",
  "state": "uploading"
}

客户端根据 received 计算缺片集合，重新发送第 3 片即可。状态响应还要带一个任务版本或文件指纹，防止用户在同一个上传 ID 下选择了另一份文件后继续复用旧分片。

合并不是简单按文件名拼接

收到合并请求时，先锁定任务状态，再检查 0 到 totalChunks-1 是否全部有合法回执。合并过程建议写入新的临时目标文件，按编号顺序读取分片并计算整文件 SHA-256；只有长度和最终哈希都通过，才把临时目标改名为正式文件。

合并成功后把任务状态改为 completed，后续分片请求统一拒绝。合并失败时保留任务为 uploading 或 merge_failed，不要把一个可能缺片的文件暴露给下载接口。多实例部署时，这个状态转换必须落在数据库或具备条件更新能力的存储中，单机内存锁只能解决一个进程的问题。

浏览器、代理和 Go 的兼容注意

分片上传不等于把所有代理配置都绕开。反向代理仍可能限制单次请求体积，浏览器也可能因为页面关闭而中止请求。分片大小应先根据网络和代理限制做保守选择，例如从 4 MiB 或 8 MiB 开始，用真实网络测量失败率和重试成本。

• 请求体读取使用流式方式，避免把一片过大的内容整体读进内存。
• 限制上传任务总数、单片大小、总文件大小和任务保留时间。
• 临时分片目录不能直接暴露为静态文件目录，正式文件也应使用不可猜的下载授权。
• 清理任务按“最后活动时间”回收过期分片，但不要删除正在合并的任务。

常见问题

可以只用分片编号，不传 Content-Range 吗？

可以由服务端根据编号推导范围，但仍建议在协议中保留并校验范围。它能发现客户端切片大小变化、总长度变化和代理改写等问题。

同一个分片重复上传会不会损坏文件？

只要服务端按分片回执做幂等判断，并用临时文件原子改名，内容一致的重复请求可以直接返回成功；内容不一致则必须拒绝或覆盖前要求重新确认。

为什么整文件还要再算一次 SHA-256？

分片校验只能证明每个局部传输正确，合并顺序、缺片检查和目标文件写入仍可能出错。整文件哈希是交付前最后一道验收。

上传任务应该保存多久？

按业务允许的断点窗口设置，例如 24 小时或 72 小时，并以最后活动时间续期。过期后删除临时分片，同时让客户端重新创建任务。

上线前的验收清单

1. 正常上传、最后一片较小、分片乱序和单片重试都能得到稳定结果。
2. 篡改 Content-Range、校验和或总长度时，服务端拒绝并清理临时文件。
3. 服务重启后能从已完成分片集合恢复，合并中的临时文件不会被当作正式文件。
4. 重复合并请求不会生成第二个正式文件，过期任务能被安全回收。