Golang 实现文件上传与断点续传方法

本文深入解析了在 Go 语言中构建高可靠性文件上传与断点续传系统的核心实践：从禁用默认的内存式 multipart 解析、手动流式处理 request.Body，到通过 URL 参数传递元信息、SHA256 实时校验分片完整性、基于 uploadId 的状态持久化与 TTL 自动清理，再到前端 JavaScript 的高效切片策略与幂等接口设计——每一步都直击大文件上传在真实生产环境中的痛点，帮你避开内存溢出、数据错乱、状态丢失等常见陷阱，真正实现稳定、可恢复、可扩展的断点续传能力。

Go HTTP 服务端如何接收分片上传的文件

Go 标准库 http.Request 默认把整个请求体读进内存，对大文件上传不友好，也撑不住断点续传的分片逻辑。必须绕过 ParseMultipartForm 的默认行为，手动读取原始 body。

关键点是：禁用自动解析，用 request.Body 直接读流，并配合 io.Copy 或 io.CopyN 写入临时文件或磁盘位置：

• 在 handler 开头调用 request.ParseMultipartForm(0)（传 0 表示不限制内存缓存），避免标准库提前消费 body
• 从 request.MultipartForm.Value["filename"] 或 request.URL.Query().Get("filename") 获取文件名（推荐 URL 参数传元信息，更可控）
• 用 request.FormValue("chunkIndex") 和 request.FormValue("totalChunks") 提取分片序号与总数
• 分片写入路径建议按 uploadID/chunk_0001.bin 组织，避免并发覆盖

客户端如何生成并发送文件分片（前端 JS 示例）

断点续传依赖客户端能切片、记录进度、重试失败分片。浏览器端用 Blob.slice() 最稳妥，不要依赖 FileReader 全量读取再切——会卡 UI 且浪费内存。

典型错误是把所有分片发成同一个 Content-Type: multipart/form-data，导致服务端无法区分 chunk 边界。正确做法是每个分片走独立 POST 请求，携带明确标识：

• URL 路径带唯一 uploadId，如 /api/upload/abc123/chunk
• 表单字段用 chunkIndex=2&totalChunks=12&filename=report.pdf，不用文件字段嵌套
• 二进制数据直接作为 request body 发送（fetch(..., { body: blob })），不包 multipart
• 务必设置 headers: { "Content-Type": "application/octet-stream" }，否则 Go 服务端可能误判边界

如何校验分片完整性并合并完成文件

只靠序号拼接不可靠——网络丢包、重复发送、客户端时钟漂移都可能导致错序或重复。必须引入内容校验机制。

推荐在上传每个分片时，由客户端计算 SHA256 并随请求发送（如 X-Chunk-Hash: a1b2c3...），服务端收到后立刻校验：

• 用 crypto/sha256.New() + io.Copy(hasher, chunkReader) 实时计算，不落地再读
• 校验失败返回 400 Bad Request + 错误信息，客户端可重传该 chunk
• 合并阶段不直接 cat 所有分片，而是按 chunkIndex 排序后，用 os.OpenFile(..., os.O_WRONLY|os.O_APPEND) 追加写入目标文件
• 合并前检查是否收齐所有分片（len(chunkFiles) == totalChunks），缺一不可，避免静默损坏

如何持久化上传状态并支持断点恢复

HTTP 是无状态的，客户端崩溃后必须能查到“已传哪几片”。不能只靠文件系统扫描，得有轻量元数据存储。

最简方案是用本地 JSON 文件或 SQLite 存每条上传的状态，字段至少包含：uploadId、filename、totalChunks、completedChunks（int 集合或位图）、updatedAt：

• 每次成功写入一个分片，就更新对应 completedChunks 并刷盘（os.WriteFile 或 db.Exec）
• 客户端发起新上传前，先 GET /api/upload/{id}/status 拉取已传列表，跳过已存在 chunkIndex
• 注意并发风险：多个 tab 同时传同一文件时，uploadId 必须全局唯一（如用 uuid.NewString()），不能靠文件名哈希
• 临时分片文件建议设 TTL，比如 24 小时未完成则自动清理，避免磁盘被占满

真正难的不是切片和合并，而是让“已传”这个状态在服务重启、客户端中断、网络分区下依然可信。校验、原子写、幂等接口、过期清理，缺一不可。

到这里，我们也就讲完了《Golang 实现文件上传与断点续传方法》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！