静态资源的缓存策略一直是 Web 应用部署中绕不开的话题。当浏览器缓存了某个 CSS 或 JS 文件后，如果服务器上文件内容发生了变化，旧缓存就会造成样式错乱或脚本异常。一种常见的做法是在文件名后追加查询字符串，例如 app.css?v=2，但这种方法需要开发者手动维护版本号，一旦忘记更新，缓存就会失效。Rack::StaticCache 提供了一种更可靠的思路：把文件内容的哈希值直接嵌入文件名，生成类似 app-7f2a9c.css 这样的指纹文件名，浏览器和 CDN 会自动把它当作一个新资源重新缓存，而缓存键就由这个指纹决定，不再依赖人为操作。
Rack::StaticCache 是 Ruby 的 Rack 中间件，可以对静态文件进行更精细的缓存控制。它的默认行为基于文件修改时间和 ETag，但通过 Rack::StaticCache::Key 模块，我们可以显式指定指纹文件名作为缓存键。这样做的好处在于，文件内容一旦改变，指纹立刻变化，缓存键也跟着变，旧缓存自然失效，CDN 和浏览器无需额外配置即可获取新文件。接下来我们分几个方面来深入分析这种实现方式。
静态文件缓存为什么不推荐只用查询字符串
很多项目在引入新版本的静态资源时，习惯在 URL 上追加 ?v=1.0.1 或者 ?t=1234567890。这种方法虽然简单，但存在几个明显问题：第一，查询字符串对部分 CDN 或代理服务器不够友好，有些 CDN 默认会忽略查询字符串作为缓存键，导致新旧版本文件混用；第二，如果多个静态资源共用同一个版本号，一旦其中一个文件单独更新，其他文件并没有变化，却也会因为 URL 变化而重新下载，浪费带宽；第三，手动更新版本号容易遗漏，尤其是在持续集成环境中，每次构建都改版本号会让提交历史非常混乱。
指纹文件名则直接把内容摘要放在文件名里，比如 app-9a1b2c3d.js。只要文件内容不同，哈希值就不同，文件名就不同。这样每个文件独立拥有自己的版本标识，粒度精确到单个文件。浏览器看到不同的 URL 会重新请求，而内容没变的文件仍然使用旧的 URL，缓存可以继续命中。这比全局版本号或时间戳要合理得多，也是现代前端构建工具（如 Webpack、Vite）默认采用的方式。Rack::StaticCache::Key 正是为了在 Rack 层面支持这种方案而设计的。
此外，查询字符串方案还有一个致命缺陷：当服务器同时收到多个并发请求时，如果缓存中间件仅根据路径（不包含查询字符串）来定位缓存条目，就可能错误命中。虽然可以通过配置来解决，但会增加复杂度。指纹文件名从根源上避免了这个问题，因为文件名本身就是不同路径，缓存键天然隔离。
Rack::StaticCache::Key 的实现与配置
要在 Rack 应用中使用指纹文件名作为缓存键，首先需要安装 rack-static_cache 这个 gem。在 Gemfile 中添加一行，然后执行 bundle install。配置中间件时，可以指定一个 :key 选项，把 Rack::StaticCache::Key 作为缓存键生成器。示例代码如下：
# Gemfile
gem 'rack-static_cache'
# config.ru
require 'rack/static_cache'
use Rack::StaticCache,
urls: ['/assets'],
root: 'public',
key: Rack::StaticCache::Key.new(
digest: 'MD5',
separator: '-'
)
run lambda { |env|
[200, {'Content-Type' => 'text/plain'}, ['Hello']]
}
上面的配置把 public/assets 目录下的静态文件交给 Rack::StaticCache 处理，并使用 Rack::StaticCache::Key 生成缓存键。构造函数的 :digest 参数可以指定 MD5、SHA1 或 SHA256，:separator 则定义了原始文件名与指纹之间的分隔符。当请求 /assets/app.js 时，中间件会读取文件内容，计算哈希值，然后在内部把缓存键设置为类似 app-9a1b2c3d.js 的字符串。
这里有一个关键细节：中间件并不会直接修改磁盘上的文件名，它只是在内存缓存层把「请求路径」映射到「指纹键」。也就是说，如果你的部署流程已经将文件重命名为带指纹的名字，Rack::StaticCache::Key 可以直接识别这类文件名；如果文件还是未加指纹的原始名，中间件会根据内容实时计算指纹并返回一个虚拟的指纹键。两种方式都可行，但为了最大程度配合 CDN 和预压缩部署，建议在构建阶段就生成带指纹的真实文件。
Rack::StaticCache::Key 内部实现了 call 方法，接收环境变量和文件路径，返回一个用来做缓存键的字符串。它会先解析路径中的文件名和扩展名，然后根据配置的哈希算法对文件内容做摘要，最后拼接成 basename-separator-digest.extension 的形式。如果文件内容为空或者读取失败，会回退到使用文件路径本身作为缓存键，确保不出现异常中断。
指纹键与 ETag、Last-Modified 的配合
指纹文件名解决了缓存失效的“何时变”问题，但 HTTP 缓存还依赖响应头中的 ETag 和 Last-Modified 来做条件请求。Rack::StaticCache 默认会为每个静态文件生成 ETag，通常是基于文件内容的弱 ETag 或强 ETag。当浏览器再次请求同一个指纹文件时，如果文件没变，ETag 相同，服务器可以返回 304 Not Modified，节省带宽。指纹文件名和 ETag 并不冲突，反而可以协同工作：指纹负责保证 URL 层面的唯一性，ETag 负责在同一次 URL 下的条件请求优化。
实际部署中，CDN 通常以完整的 URL（包括文件名）作为缓存键，指纹文件名的变化会自动触发 CDN 回源获取新文件。而 ETag 的存在允许 CDN 在回源时使用条件请求，进一步减少传输的数据量。如果单独使用 ETag 而不用指纹文件名，旧的 URL 可能被 CDN 缓存太久，即使 ETag 变了，CDN 也不一定会主动回源验证。因此两者配合是最佳实践。
需要注意的是，Rack::StaticCache::Key 生成的指纹键并不会改变响应头中的 ETag 值，它只影响中间件内部使用的缓存键。如果希望 ETag 也基于指纹键，可以自定义中间件重写 ETag 头，但一般没必要，因为文件内容指纹和 ETag 通常是一致的。只要确保哈希算法与 ETag 算法一致，就不会出现矛盾。
与 Rails Asset Pipeline 的异同及部署建议
Rails 的 Asset Pipeline 从很早开始就把指纹文件名作为默认行为，例如 application-7f2a9c3d4e5f.css。Rack::StaticCache::Key 在非 Rails 的 Rack 应用中提供了类似的能力，让 Sinatra、Padrino 或纯 Rack 项目也能享受相同的好处。区别在于 Rails 是在构建阶段生成带指纹的真实文件，并由 Sprockets 或 Propshaft 管理引用关系；而 Rack::StaticCache::Key 更偏向运行时动态计算，适合那些没有复杂构建流程的小型项目，或者在已有构建步骤之外额外增加一层保护。
如果你的项目已经使用 Webpack、Vite 等前端工具打包，建议继续沿用它们的指纹输出，因为构建工具能在 HTML 中自动替换引用链接。Rack::StaticCache::Key 可以在服务器层面作为兜底，防止有人直接访问未加指纹的旧文件路径。对于纯静态站点或 API 服务中的少量静态资源，直接启用这个中间件就能获得可靠的缓存失效机制。
部署时还需注意 CDN 的缓存规则。指纹文件名天然支持长缓存策略，可以设置 Cache-Control: public, max-age=31536000, immutable，因为文件名不变就代表内容不变。但如果中间件动态计算指纹，而文件在服务器上仍然是无指纹的原始名，那么请求路径可能不带指纹，这时需要中间件在响应头中自动添加指纹或重定向到指纹 URL，否则浏览器无法感知变化。Rack::StaticCache 提供了 :redirect 选项，可以自动把无指纹请求重定向到带指纹的路径，这也是一个实用的补充。
总体来看，Rack::StaticCache::Key 把指纹文件名作为缓存键的实现，既符合现代 Web 缓存的最佳实践，又保持了 Rack 中间件的轻量特性。它让开发者不再为静态资源版本号绞尽脑汁，通过内容哈希实现了缓存失效的自动化。在实际项目中使用时，结合构建期指纹和运行时回退，可以构建一套健壮的静态资源缓存体系。
Rack::StaticCache指纹文件名缓存键修改时间：2026-09-18 11:13:14