Rails应用为什么天生用不了Service Workerserviceworker-rails完整指南一个Gem破解PWA缓存与Scope两大死结【免费下载链接】serviceworker-railsUse Service Worker with the Rails asset pipeline项目地址: https://gitcode.com/gh_mirrors/se/serviceworker-rails 一句话结论Rails 的资产管线和 Service Worker 的生存规则天生相冲指纹化让文件永不更新而/assets目录又给 Worker 套上了作用域枷锁。开源 Gemserviceworker-rails正是为此而生——一个中间件 一个路由映射就能让你的 Rails 应用变成支持离线缓存、可安装到手机主屏的 Progressive Web AppPWA无需换框架、无需额外部署层。一、为什么 Rails 应用天生接不住 Service Worker先说背景Service Worker 是运行在浏览器独立线程里的请求代理能拦截请求、填充缓存、实现离线访问是 PWA 的灵魂。但它有两条硬性规则恰好条条踩中 Rails 的默认设计。死结一指纹化缓存 vs Service Worker 的定时更新Rails 资产管线Sprockets为了极致的可缓存性会给每个文件加内容指纹比如application-abc123.js并配上长期有效的Cache-Control头。文件内容一变URL 就变——这套不可变 URL策略对普通资源完美。但浏览器检查 Service Worker 更新的方式是每隔 24 小时甚至更久去请求同一个 URL对比脚本内容是否有变化。URL 被指纹化锁死后浏览器永远看不到新脚本你的 Service Worker 更新机制就此失效。死结二/assets 目录 vs Scope 作用域限制浏览器规定Service Worker 只能控制它自身所在目录及其子目录下的请求即 scope。如果 Worker 脚本放在/assets/serviceworker-abc123.js它就只能干预/assets/下的资源——而你的页面、API、HTML 全在这个目录之外。缓存整个应用无从谈起。这就是两大死结的由来。二、serviceworker-rails 是什么它怎么破解一句话它不改 Rails 的指纹策略而是为 Service Worker 文件单开一条绿色通道。拦截请求中间件在 Rails 静态文件处理之前先识别这是 Service Worker 请求新鲜交付给 Worker 文件返回不带指纹的 URL并加上Cache-Control: no-cache头浏览器就能按时检查到新版本破开 Scope用路由映射把 Worker 挂到根路径/serviceworker.js作用域天然覆盖整个应用对应到源码核心就三块都放在lib/目录下组件文件位置职责路由映射器lib/serviceworker/router.rb把/serviceworker.js这类 URL 映射到 Sprockets 资产名请求中间件lib/serviceworker/middleware.rb拦截请求、注入正确的缓存响应头Sprockets 处理器lib/serviceworker/handlers/sprockets_handler.rb开发时实时编译、生产时直接返回预编译结果安装后Gem 的引擎文件lib/serviceworker/engine.rb会自动把中间件插入 Rails 中间件栈你几乎不需要手写任何 Ruby 代码。三、安装与一键生成3 步上手第 1 步添加依赖在项目的Gemfile中加入一行gem serviceworker-rails然后执行bundle安装即可也可以gem install serviceworker-rails手动安装。第 2 步运行生成器自动铺好所有文件在项目根目录执行rails g serviceworker:install生成器源码见lib/generators/serviceworker/install_generator.rb会一次性创建 5 个文件文件作用config/initializers/serviceworker.rb路由映射配置告诉中间件哪些 URL 是 Workerapp/assets/javascripts/serviceworker.js.erb你的 Service Worker 脚本支持 ERB 模板app/assets/javascripts/serviceworker-companion.js浏览器端注册 Worker 的伴侣脚本app/assets/javascripts/manifest.json.erbWeb App 清单让应用可安装public/offline.html离线兜底页面同时它会自动把serviceworker.js和manifest.json加入预编译清单config/initializers/assets.rb并在app/views/layouts/application.html.erb的head里注入 manifest 链接标签。第 3 步引入伴侣脚本在你的 JS 入口app/assets/javascripts/application.js末尾加一行// require serviceworker-companion如果用 Importmaps app/javascript目录把生成的文件挪过去改用import serviceworker-companion即可。四、避坑指南3 个新手最常踩的雷 ⚠️别让require_tree吞掉 Worker 脚本。Service Worker 跑在独立线程绝不能打进application.js。如果你的入口文件里有// require_tree .请把serviceworker.js移走或换成显式引用。注册失败先查协议。Service Worker 只在 HTTPS或 localhost下生效。本地开发用localhost:3000没问题部署到远程服务器必须配置 SSL否则伴侣脚本会静默失败。想扩展作用域要加响应头。默认 scope 是 Worker 所在目录。若需跨目录控制可在 initializer 中通过config.serviceworker.headers添加实验性的Service-Worker-Allowed头详见lib/serviceworker/middleware.rb的默认头逻辑。五、验证你的 PWA 是否生效4 项检查清单重启 Rails 服务用 Chrome 或 Firefox 打开页面按顺序确认Console 出现[Companion] Rails Service worker registered!—— 注册成功 ✅DevTools → Application → Caches里出现缓存名如v1-cached-assets缓存列表中能看到你预填充的application.js、application.css、/offline.html断网刷新页面或 DevTools 里把网络调成 Offline离线页正常展示 —— 离线能力打通 六、从能缓存到真好用升级路线生成器给你的serviceworker.js.erb是一个带示例策略的起点常见演进路径阶段一onInstall里预填充静态资源 离线页模板已给出示例阶段二onFetch里拦截请求实现网络优先 → 缓存兜底 → 离线页兜底的策略阶段三缓存版本迭代——缓存名带上版本号v1、v2在onActivate里清掉旧版本缓存写在最后两大死结的本质指纹化让资源不可变而 Service Worker 需要固定 URL 持续更新。serviceworker-rails 的解法不是推翻 Rails 的设计而是给 Worker 单开一条不受指纹与缓存头约束的通道再把它放到作用域最宽的根路径。gem serviceworker-rails 一行生成器 一行 require你的 Rails 应用就离 PWA 只差一段缓存策略的代码了。【免费下载链接】serviceworker-railsUse Service Worker with the Rails asset pipeline项目地址: https://gitcode.com/gh_mirrors/se/serviceworker-rails创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
