Rails框架虽然强大，但有时候我们只是需要一个简单的文件服务器，比如在内网共享文档、给前端项目提供静态资源、或者调试时快速浏览目录结构。这时完全可以直接使用Rack自带的两个中间件：Rack::Static负责静态文件服务，Rack::Directory负责目录浏览，把它们组合起来，几十行代码就能实现一个小巧实用的文件服务工具，不需要引入任何额外的gem。
一、Rack中间件的基础工作机制
在深入这两个中间件之前，先简单回顾一下Rack的工作方式。Rack定义了一个极简的接口：任何响应call方法、接受环境哈希并返回[status, headers, body]三元组的对象，都可以作为Rack应用。中间件则在此基础上把请求包裹起来，在调用下游应用之前或之后做一些额外处理，比如日志记录、会话管理、静态文件解析等。
Rack::Static和Rack::Directory就是两个典型的中间件。它们的行为逻辑截然不同：Rack::Static在匹配到静态文件时直接返回文件内容，否则把请求传递给下游应用；Rack::Directory则是一个独立应用，它接收请求后渲染出目录列表的HTML页面。理解这个区别很重要，因为Static更像一个过滤器，而Directory更像一个终点处理器。
Rack中间件是按顺序叠加的，请求从外层流向内层。合理排列Static和Directory的顺序，可以做到既有目录浏览能力，又能正确返回目录下的index.html。下面会结合具体代码说明。
二、Rack::Static的配置与用法详解
Rack::Static的核心作用是根据URL前缀将请求映射到磁盘上的文件。最常用的三个参数是:urls、:root和:index。看一个基本示例：
use Rack::Static, urls: ["/images", "/css", "/js"], root: "public"
这段配置表示：当请求路径以/images、/css或/js开头时，中间件会在public目录下查找对应文件。比如请求/css/main.css，实际读取的是public/css/main.css。如果文件存在，中间件返回200和文件内容；不存在则交给下游应用处理。
:urls参数有两种写法需要注意。写成数组形式时，匹配的是路径前缀；而写成["/"]则匹配所有请求，相当于全局静态服务。此外还支持:index参数，用来指定匹配到目录时优先返回的默认文件：
use Rack::Static, urls: ["/"], root: "public", index: "index.html"
配置了index后，访问/docs/会自动返回public/docs/index.html。Rack::Static会根据文件扩展名自动推断Content-Type，比如.css返回text/css，.png返回image/png。如果遇到不认识的扩展名，默认返回text/plain，可以通过:content_type参数覆盖这个默认值。
还有一个不太显眼但很实用的参数:gzip。设为true后，当请求头带有Accept-Encoding标记gzip且磁盘上存在同名.gz文件时，中间件会优先返回压缩版本，并设置Content-Encoding响应头，对提升静态资源加载速度很有帮助。
三、Rack::Directory实现目录浏览
Rack::Directory的行为类似传统的Apache目录列表：访问某个目录时，返回一个包含文件名、大小、修改时间的HTML页面，并支持点击进入子目录或下载文件。它的用法非常简单：
require "rack/directory"
run Rack::Directory.new("/var/share/files")
构造函数的参数是磁盘上真实存在的目录路径。如果传入的目录不存在，初始化时会直接抛出异常，所以最好在启动前做一次存在性检查。Rack::Directory返回的页面自带简单的样式，文件按字母顺序排列，目录后面带斜杠标识，最后一行还会显示服务器的环境信息。
它的响应头处理也比较到位：文件下载时会设置Content-Type和Content-Length，对浏览器无法直接打开的文件还会触发下载行为。需要注意的一点是，Rack::Directory只服务目录和文件，它本身不处理index.html的逻辑，也就是说，如果目录下有index.html，访问该目录时依然显示列表而非渲染index页面，这一点与Nginx的autoindex行为一致。
四、组合两者搭建一个完整的小型文件服务器
单独使用每个中间件都有局限，组合起来才能覆盖完整场景。思路是：请求先经过Rack::Static，尝试匹配静态文件和index.html；匹配不到时，再交给Rack::Directory渲染目录列表。用一个config.ru即可实现：
require "rack"
require "rack/directory"
ROOT = File.expand_path("public", __dir__)
use Rack::Static,
urls: ["/"],
root: ROOT,
index: "index.html"
run Rack::Directory.new(ROOT)
启动方式就是标准的Rack启动命令：
rackup config.ru -p 9292 -o 0.0.0.0
这样访问根路径时，如果根目录下有index.html则显示页面，否则展示目录列表；访问具体文件时直接返回文件内容。整个文件服务器没有一行框架代码，纯Rack实现，依赖极少，启动速度快。
如果希望增加一些附加功能，可以再叠加其他中间件，比如用Rack::CommonLogger记录访问日志，用Rack::Deflater对文本响应做gzip压缩。中间件顺序建议把日志放在最外层，这样所有请求包括静态资源都能被记录下来。
五、常见坑点与注意事项
第一是路径穿越问题。Rack::Static和Rack::Directory内部都对路径做了规范化处理，会拒绝包含点点这类恶意相对路径的请求，这一点可以放心。但如果你自己在外层做了URL重写，务必确保重写后的路径仍然在root目录之内，否则可能引入安全隐患。
第二是中文文件名编码。Rack::Directory生成的HTML页面使用UTF-8编码，现代浏览器基本没有问题，但URL中的非ASCII字符需要正确解码后才能定位到磁盘文件。如果遇到404，可以手动解码URL排查，确认是编码问题还是文件确实不存在。
第三是缓存控制。这两个中间件默认不输出Cache-Control头，浏览器每次都可能重新请求。对更新频繁的内部文件服务这是合理的，但如果服务于长期不变的静态资源，建议在外层包一个自定义中间件，根据文件扩展名添加类似max-age为一天的Cache-Control响应头，能显著减少重复下载。
第四是并发与大文件。Rack中间件返回文件时使用的是流式响应，大文件不会一次性读入内存，内存占用可控。但在单进程模式下，大文件下载会占用一个worker，如果并发下载需求较高，建议配合多进程服务器（如Puma的cluster模式）或者直接改用Nginx等专业静态服务器做前置。
六、适用场景与替代方案对比
Rack方案的优势在于零额外依赖、与Ruby应用天然集成、代码可定制性强。它非常适合这些场景：内网文档共享、CI环境下的构建产物预览、开发时的临时资源服务、嵌在Ruby脚本里的小型工具。通过继承Rack::Directory并重写渲染方法，你甚至可以自定义目录页面的样式和展示逻辑，这是很多现成工具做不到的。
当然它也有边界。如果是面向公网的高流量静态资源服务，Nginx或CDN在性能、缓存控制、安全加固方面都更成熟；如果需要对象存储语义，则应该考虑专用存储服务。Rack::Static和Rack::Directory的最佳定位是轻量、内嵌、开发友好，在Ruby生态内部快速提供文件能力。
总结一下，掌握这两个中间件的关键在于理解urls映射规则和中间件的传递顺序。Static优先匹配文件和索引页，Directory兜底处理目录浏览，两者配合既能覆盖常规静态服务，又能提供灵活的文件浏览体验，是每个Ruby开发者工具箱里值得常备的技能。
Rack::StaticRack::DirectoryRack中间件修改时间：2026-09-15 18:57:02