Ruby Faraday Multipart临时文件清理怎么做？Tempfile自动释放机制详解

Ruby的Tempfile本身设计得相当聪明，它会在对象被垃圾回收时自动删除对应的磁盘文件。但很多使用Faraday做文件上传的同学会发现，服务器运行一段时间后，/tmp目录下还是堆积了大量带Faraday前缀的临时文件。明明有GC兜底，为什么还会泄漏？这篇文章就来彻底拆解Faraday Multipart上传中临时文件的来龙去脉，以及如何保证它们被可靠清理。

一、Tempfile的生命周期与自动清理机制

要理解清理问题，先要看清楚Tempfile是怎么工作的。Tempfile继承自File，构造时会调用Dir::Tmpname创建一个唯一命名的临时文件，同时注册一个finalizer（终结器）。当Tempfile对象没有任何引用、被垃圾回收器回收时，finalizer会负责删除磁盘上的文件。

这个机制的隐患在于：GC的触发时机是不确定的。Ruby的垃圾回收并不是引用计数式的即时释放，而是要等到堆内存压力达到阈值才运行。也就是说，临时文件在磁盘上停留多久，完全取决于GC什么时候想起它。在低内存占用的长驻进程里（比如Sidekiq worker），一个持有几KB临时文件的对象可能几个小时都不会被回收，磁盘垃圾就这么悄悄累积起来了。

另一个更隐蔽的坑是引用泄漏。如果你把Tempfile对象塞进了一个长期存活的数组、类变量或者闭包里，GC永远不会判定它可回收，finalizer也就永远不会执行，文件就永久留在磁盘上了。所以在讨论Faraday之前，先记住一条原则：自动清理只是兜底，不能当作主要手段。

二、Faraday中FilePart的临时文件从哪里来

先看一个典型的Multipart上传代码：

conn = Faraday.new(url: "https://api.ipipp.com") do |f|
  f.request :multipart
  f.request :url_encoded
  f.adapter :net_http
end

payload = { file: Faraday::FilePart.new("/path/to/large.bin") }
conn.post("/upload", payload)

这里的Faraday::FilePart（老版本叫Faraday::UploadIO）在处理非文件对象时，会把内容写入一个Tempfile。典型场景有三种：你传入的是StringIO或纯字符串、传入的是需要重新编码的IO流、或者请求重试时需要可回读的源。对于普通文件路径，FilePart直接持有File对象，不产生临时文件；而一旦涉及内存流，Tempfile就诞生了。

排查泄漏时有个实用技巧：观察文件名。Tempfile生成的文件名格式通常是系统前缀+随机串，你可以全局搜索代码中对Tempfile.new、Tempfile.create、StringIO的调用，确认到底是哪一层创建了临时文件。常见的泄漏源头其实是业务代码自己：有人先用Tempfile接住了下载内容，再传给Faraday，之后忘了关闭，Faraday只是背了锅。

三、可靠的清理方案：从手动到自动化

最直接可靠的方式是使用ensure块，保证无论请求成功还是抛异常，临时文件都会被关闭删除：

tmp = Tempfile.create("upload")  # create形式块结束时自动关闭并删除
begin
  tmp.write(content)
  tmp.rewind
  payload = { file: Faraday::FilePart.new(tmp, "application/octet-stream") }
  conn.post("/upload", payload)
ensure
  tmp.close unless tmp.closed?
  File.delete(tmp.path) if File.exist?(tmp.path)
end

注意Tempfile.create和Tempfile.new的区别：前者在块结束时自动删除文件，后者需要显式调用close!（带感叹号的版本才会删文件，普通close只关闭句柄）。这是很多同学踩过的坑——调用了close却发现文件还在，原因就在这里。

如果临时文件是由框架或第三方库创建的，你拿不到创建时机，可以在请求完成后统一扫描清理。比如在Rack中间件里记录请求期间产生的Tempfile路径，请求结束时批量删除；或者部署一个定期任务，清理超过一定时间的/tmp文件：

# 定期清理超过1小时的Faraday相关临时文件
require "tmpdir"
Dir.glob(File.join(Dir.tmpdir, "*")).each do |path|
  if File.mtime(path) < Time.now - 3600
    File.delete(path) rescue nil
  end
end

这个兜底方案虽然看起来不够优雅，但在生产环境非常实用，能有效防止磁盘被撑爆。最后再强调几个要点：优先使用Tempfile.create的块形式；用close!而不是close；不要把Tempfile对象存进长生命周期结构；对不可控来源的临时文件，用定期任务兜底。做到这几点，Faraday上传的临时文件问题基本就绝迹了。

FaradayMultipartTempfile清理修改时间：2026-09-15 14:16:38