大文件上传占满内存通常错在哪里，何时应流式读取

Go HTTP 服务接收大文件时，内存突然上涨，最常见的错误并不是“用了 multipart”，而是解析之后又调用 io.ReadAll、把内容写进 bytes.Buffer，或者为了计算哈希、识别格式而同时保留多份完整字节。ParseMultipartForm 本身会把超出内存额度的文件部分写到临时磁盘；真正需要先建立的是总请求上限、单文件上限和复制次数的边界。

小文件、字段数量固定且业务需要随机访问表单时，可以继续使用 ParseMultipartForm；文件达到数百 MB、并发较高、希望边接收边落盘，或者不想让服务端先解析完整表单时，应改用 MultipartReader 流式处理。

为什么上传会把内存顶满

先区分三个概念：请求体有多大、multipart 解析器把多少文件内容留在内存、业务代码又复制了多少份。它们不是同一个上限。

• http.MaxBytesReader 限制整个请求体，读过界时返回 *http.MaxBytesError。
• ParseMultipartForm(maxMemory) 会解析完整 multipart 请求；文件部分最多有 maxMemory 字节留在内存，剩余内容进入临时文件。
• mime/multipart.Reader.ReadForm 还为非文件字段预留额外内存，因此 maxMemory 不能当作“进程最多占这么多内存”。
• io.ReadAll(file)、bytes.Buffer 和 []byte 转换会在业务层重新创建完整副本。

旧写法的问题：解析后又把文件全部读进内存

下面这种写法看起来简单，但 FormFile 会在需要时触发 ParseMultipartForm，随后 io.ReadAll 又为文件创建一份完整字节切片。一个 800 MB 文件即使已经被 multipart 解析器放入临时磁盘，业务层仍可能再申请接近 800 MB 的连续内存。

file, _, err := r.FormFile("file")
if err != nil {
    http.Error(w, "读取上传文件失败", http.StatusBadRequest)
    return
}
defer file.Close()

data, err := io.ReadAll(file) // 错误点：为整个文件再分配一份内存
if err != nil {
    http.Error(w, "读取文件内容失败", http.StatusInternalServerError)
    return
}
_ = data

如果后面又把 data 写入 bytes.Buffer、上传 SDK 或解码器，峰值还可能继续叠加。排查时不要只看 Content-Length，应通过 heap profile 或分配采样确认大对象究竟来自解析器、io.ReadAll，还是后续编码过程。

小文件方案：先限制总请求，再解析表单

普通头像、证书或配置包等小文件，如果接口需要同时访问多个表单字段，ParseMultipartForm 仍然很合适。关键是先用 MaxBytesReader 限制整个请求体，并在完成后调用 MultipartForm.RemoveAll 清理临时文件。

func uploadSmall(w http.ResponseWriter, r *http.Request) {
    const maxRequestBytes int64 = 32 

这里的 memoryBudget 只影响 multipart 文件内容在内存与临时磁盘之间的分配，不能替代 maxRequestBytes。另外，客户端文件名只能用于显示或审计，不能直接拼进服务端路径；目标文件名应由服务端生成。

什么时候应改用 MultipartReader 流式读取

Go 官方把 Request.MultipartReader 定义为“以流方式处理请求体”的入口。它返回一个按 part 迭代的读取器，NextPart 每次只交出当前字段。于是服务端可以边收边写，不必先把完整 multipart 表单解析完。

新规则：总请求限额和单文件限额要分开

流式处理不会自动变安全。整个请求可能包含多个 part，也可能用大量普通字段消耗资源。因此示例同时设置总请求上限和单文件上限，只接受一个名为 file 的文件字段，并在任何错误下删除半成品。

package upload

import (
    "errors"
    "io"
    "net/http"
    "os"
)

var errFileTooLarge = errors.New("file too large")

func uploadLarge(w http.ResponseWriter, r *http.Request) {
    const maxRequestBytes int64 = (1  maxBytes {
        return errFileTooLarge
    }
    if err := dst.Sync(); err != nil {
        return err
    }
    if err := dst.Close(); err != nil {
        return err
    }
    keep = true
    return nil
}

io.CopyBuffer 的缓冲区大小决定单次复制占用，不会随着文件变大而等比例增长。io.LimitReader(maxBytes+1) 则让代码能识别“恰好等于上限”和“已经超过上限”的差别。生产环境还应把目标目录放在独立配额、权限受控的存储上，并监控磁盘空间和写入耗时。

兼容与安全注意

• 不要只信 Content-Length：它可能缺失，也可能与实际读取量不一致；真正的限制必须包在读取器上。
• 限制字段和文件数量：流式接口应明确允许的字段名、文件数、普通字段长度和 part 数量。
• 校验内容而非扩展名：客户端文件名和 MIME 声明都可伪造；若业务需要类型判断，应读取小段前缀并重放或单独保存，不要读取整个文件。
• 哈希也可以流式计算：使用 io.MultiWriter(dst, hasher) 同时落盘和计算摘要，避免先读成 []byte。
• 区分中断与成功：客户端断开、磁盘写满或校验失败时删除半成品；真正发布文件前再用原子重命名或记录状态。
• 代理层和应用层都要有限额：反向代理的限制负责尽早拒绝异常流量，应用层限制负责保证业务边界，两者不能互相替代。

采用建议

如果当前接口只是因为一句 io.ReadAll 导致内存暴涨，先删掉整份复制，改用 io.Copy 或 io.CopyBuffer，通常就能解决主要问题；不必为了“看起来更高级”立即重写全部表单处理。只有当完整表单解析本身造成高延迟、临时磁盘压力，或文件和并发规模已经明显增大时，再切换到 MultipartReader。

最终检查顺序可以固定为：整个请求是否有硬上限、单文件是否有独立上限、业务代码是否保留完整副本、失败时是否删除半成品、客户端文件名是否进入路径。五项都明确后，大文件上传的内存行为才真正可预测。

常见问题

把 maxMemory 设成 8 MB，上传 1 GB 文件会直接失败吗？ 不一定。ParseMultipartForm 会把无法留在内存的文件部分写入临时磁盘；要拒绝 1 GB 请求，应使用 MaxBytesReader 或其他读取层限额。

流式读取是否完全不占内存？ 不是。multipart 头、固定复制缓冲区、校验器和业务元数据仍占内存，只是占用不再随着文件主体线性增长。

FormFile 适合大文件吗？ 它可以打开已解析的文件部分，但会按需触发表单解析。若目标是边接收边处理、避免完整表单先落临时区，使用 MultipartReader 更直接。

官方参考

• net/http：MaxBytesReader
• net/http：Request.ParseMultipartForm
• net/http：Request.MultipartReader
• mime/multipart：Reader.NextPart