文件上传到一半断开后临时文件为何没有删除

上传到一半客户端断开，临时文件却留在磁盘上，通常不是 multipart.Part 本身“忘记删除”，而是应用混淆了两类文件的所有权：ParseMultipartForm 生成的文件归 multipart.Form 管理；使用 MultipartReader 后自行 os.CreateTemp 创建的文件归应用管理。

最快修复：每次 os.CreateTemp 成功后立刻注册“关闭 + 失败时删除”的 defer，不要等 io.Copy 成功后才注册。只有文件已经安全迁移到最终存储时，才把清理标志改为保留。

官方文档：https://pkg.go.dev/mime/multipart#Form.RemoveAll

原因一：误以为 MultipartReader 会管理自建临时文件

Request.MultipartReader() 返回的是流式 Reader。应用通过 NextPart() 逐个读取字段，它不会替应用决定把文件写到哪里，也不知道应用后来创建了哪些临时文件。因此，下面这类文件不会被 multipart.Form.RemoveAll() 发现：

part, err := mr.NextPart()
if err != nil {
	return err
}
defer part.Close() // 只关闭当前 Part，不删除应用创建的磁盘文件。

tmp, err := os.CreateTemp(uploadTmpDir, "incoming-*")
if err != nil {
	return err
}

// 如果客户端在复制过程中断开，这里返回后仍可能留下 tmp。
_, err = io.Copy(tmp, part)
return err

part.Close() 负责当前 multipart 段的读取生命周期，tmp.Close() 负责文件描述符，os.Remove(tmp.Name()) 才负责目录项。三者不是同一件事。

原因二：删除 defer 注册得太晚

一种常见写法是等 io.Copy 成功后再 defer os.Remove(path)。客户端中途断开时，复制先返回错误，函数直接 return，清理代码从未注册。正确顺序是创建成功后立即注册。

func stagePart(ctx context.Context, part io.Reader, dir string) (path string, err error) {
	f, err := os.CreateTemp(dir, "incoming-*")
	if err != nil {
		return "", fmt.Errorf("创建临时文件: %w", err)
	}

	path = f.Name()
	keep := false
	closed := false
	defer func() {
		// 无论从哪条错误路径返回，都先释放文件句柄。
		if !closed {
			_ = f.Close()
		}
		// 只有明确完成所有权转移后才保留文件。
		if !keep {
			_ = os.Remove(path)
		}
	}()

	// 请求体断开通常会让 Read 返回错误；同时保留上下文检查。
	if _, err = io.CopyBuffer(f, &contextReader{ctx: ctx, r: part}, make([]byte, 32

这里的 keep 不是“复制成功就永久保留”，而是表示临时文件所有权从 helper 转移给调用方。调用方仍必须在保存失败时删除它。

让上下文取消参与每次读取

请求断开后，r.Context() 会被取消。请求 Body 通常也会让正在进行的读取返回错误，但给通用 Reader 增加上下文检查，可以让清理意图更明确。

type contextReader struct {
	ctx context.Context
	r   io.Reader
}

func (r *contextReader) Read(p []byte) (int, error) {
	select {
	case 

这个包装器无法中断一个完全不响应取消、已经卡住的任意 Reader；对 HTTP 请求体而言，连接关闭与服务器超时仍是解除底层读取的关键。服务器应同时配置读取超时和总请求大小限制。

ParseMultipartForm 的临时文件该怎么处理

ParseMultipartForm(maxMemory) 会解析整个表单，文件内容超过内存预算时可能写入磁盘。成功后，临时文件记录在 r.MultipartForm 中，RemoveAll() 用于删除它们。

func handleParsedForm(w http.ResponseWriter, r *http.Request) {
	if err := r.ParseMultipartForm(8 

Go 标准 HTTP 服务器在请求完成路径也会清理 Request.MultipartForm，标准库的 ReadForm 在解析出错时会移除自己已经创建的临时文件。但显式调用 RemoveAll 仍有两个好处：代码清楚表达所有权，且清理错误可以进入日志。它不会删除应用在别处创建、没有登记到 Form 中的文件。

原因三：成功标志设置过早

文件复制完成不等于业务成功。病毒扫描、格式校验、对象存储上传、数据库登记都可能失败。如果复制刚完成就取消删除 defer，后续任何错误都会留下文件。

func receiveUpload(r *http.Request, part io.Reader) error {
	path, err := stagePart(r.Context(), part, uploadTmpDir)
	if err != nil {
		return err
	}
	owned := true
	defer func() {
		// 只要没有完成最终迁移，就回收本地暂存文件。
		if owned {
			_ = os.Remove(path)
		}
	}()

	if err := scanFile(r.Context(), path); err != nil {
		return fmt.Errorf("文件扫描失败: %w", err)
	}
	if err := moveToFinalStorage(path); err != nil {
		return fmt.Errorf("迁移最终存储失败: %w", err)
	}

	owned = false // 最终存储已接管，临时路径不再由当前函数删除。
	return nil
}

若最终操作使用 os.Rename，应先关闭文件，尤其要考虑不同平台对已打开文件的重命名限制。若目标目录与临时目录不在同一文件系统，Rename 可能失败，需要复制到目标后再删除源文件，并保留相同的失败清理策略。

原因四：把请求工作放进后台 goroutine

handler 返回意味着请求生命周期结束。后台 goroutine 若继续读取 r.Body、multipart.File 或依赖 r.MultipartForm 的临时文件，会和请求结束清理产生竞态。相反，若 goroutine 接管了应用自建文件，却没有定义完成、失败和超时后的删除，也会形成长期残留。

更安全的边界是：handler 内完成请求体落盘并关闭所有请求资源，然后把一个拥有明确生命周期的任务记录或最终存储键交给后台工作器。不要把 Request、Part 或打开的 multipart 文件句柄直接传出请求。

原因五：进程被强制终止，defer 根本没有机会执行

正常 return、传播的 panic 会执行已经注册的 defer；os.Exit、SIGKILL、容器强杀、宿主机掉电不会。只靠 defer 无法保证磁盘永远没有残留，因此上传临时目录还需要进程外或启动时回收。

func removeExpiredUploads(dir string, olderThan time.Duration) error {
	entries, err := os.ReadDir(dir)
	if err != nil {
		return fmt.Errorf("读取临时目录: %w", err)
	}
	deadline := time.Now().Add(-olderThan)

	for _, entry := range entries {
		if entry.IsDir() || !strings.HasPrefix(entry.Name(), "incoming-") {
			continue // 只处理当前服务命名空间中的普通文件。
		}
		info, err := entry.Info()
		if err != nil {
			continue // 单个文件失败不阻断整次清扫，另行记录指标。
		}
		if info.ModTime().Before(deadline) {
			_ = os.Remove(filepath.Join(dir, entry.Name()))
		}
	}
	return nil
}

TTL 必须大于正常上传和后处理的最长时间，避免删除仍在使用的文件。更稳妥的实现会使用独立目录、租约文件或任务状态表标记活跃上传，并统计残留数量、总字节和最老文件年龄。

如何模拟“上传一半断开”

不要只测试完整请求。可使用 io.Pipe 作为请求体，让客户端 goroutine 写入一部分 multipart 数据后关闭管道并返回错误。通过真实 httptest.Server 发送请求，更接近 net/http 的请求结束行为。

func TestInterruptedUploadRemovesTempFile(t *testing.T) {
	before := mustListTempFiles(t, uploadTmpDir)

	pr, pw := io.Pipe()
	req, err := http.NewRequest(http.MethodPost, testServer.URL+"/upload", pr)
	if err != nil {
		t.Fatal(err)
	}
	req.Header.Set("Content-Type", "multipart/form-data; boundary=test-boundary")

	go func() {
		// 写入合法 Part 头和部分正文，然后模拟网络中断。
		_, _ = io.WriteString(pw, "--test-boundary\r\n"+
			"Content-Disposition: form-data; name=\"file\"; filename=\"a.bin\"\r\n\r\n"+
			"partial-content")
		_ = pw.CloseWithError(errors.New("模拟客户端断开"))
	}()

	_, _ = http.DefaultClient.Do(req) // 关注服务端清理结果，不依赖客户端错误文本。
	after := mustListTempFiles(t, uploadTmpDir)
	if diff := cmp.Diff(before, after); diff != "" {
		t.Fatalf("临时文件发生残留 (-before +after):\n%s", diff)
	}
}

测试还应覆盖：复制成功但扫描失败、最终迁移失败、请求超时、重复上传、磁盘写满和服务重启后的过期清扫。若使用直接调用 handler 的单元测试，不要假设完整 HTTP 服务器的请求结束清理一定会运行。

排查清单

常见问题

关闭 multipart.Part 会删除磁盘文件吗？

不会。Part.Close 结束当前段的读取；删除应用自建文件需要 os.Remove，删除 Form 管理的文件需要 MultipartForm.RemoveAll。

客户端断开后 r.Context 一定会取消吗？

服务器处理中的请求上下文会在客户端连接关闭、请求取消或 handler 返回时取消，但底层读取解除还依赖连接和超时行为。清理代码仍应以所有返回路径都能执行为目标。

有 net/http 自动清理，还要显式 RemoveAll 吗？

标准服务器会清理 Request.MultipartForm，但显式调用更容易审计并记录错误。无论哪种方式，都不会替你删除自行 CreateTemp 的文件。

为什么重启后还能看到旧文件？

强制退出时 defer 不执行，或者这些文件已经转交后台任务但任务未完成。需要 TTL 清扫和任务状态回收作为进程级兜底。

判断临时文件为什么没删，先不要从“网络断了”出发，而要从“谁创建、谁持有、何时转移所有权”出发。标准库 Form、自建临时文件和最终存储是三段不同生命周期；每段都要有成功路径、失败路径和进程崩溃后的回收方案。