Sprockets不是唯一答案serviceworker-rails搭配Importmaps与现代Rails资产栈的完整实践【免费下载链接】serviceworker-railsUse Service Worker with the Rails asset pipeline项目地址: https://gitcode.com/gh_mirrors/se/serviceworker-railsserviceworker-rails是一个让 Service Worker 与 Rails 资产管道无缝配合的 Ruby gem它能把你的 Rails 应用直接变成可离线、可安装的渐进式 Web 应用PWA。本文面向新手完整讲解 serviceworker-rails 的工作原理与安装配置步骤并给出它与 Importmaps、JSBuild 等现代 Rails 资产栈搭配使用的实践方案——即使你不使用 Sprockets也能顺利落地。为什么 Rails 需要 serviceworker-railsService Worker 与 Sprockets 的缓存冲突在理解这个 gem 之前先搞清楚一个背景Rails 默认的资产管道和 Service Worker 的游戏规则是冲突的 。作用域限制Service Worker 只能拦截它自身所在目录的请求。如果 SW 文件从/assets/serviceworker-abcd1234.js加载它就只能管/assets/下的请求这显然不是我们想要的。更新机制冲突浏览器会每 24 小时甚至更短在后台检查 Service Worker 脚本是否有更新。而 Sprockets 的指纹哈希策略意味着同一 URL 的资产不可变加上长时效的Cache-Control响应头SW 永远无法被更新。serviceworker-rails 的解法用中间件拦截对/serviceworker.js这类固定路径的请求由 Rails 实时编译开发环境或直接读取预编译产物生产环境并返回同时自动注入Cache-Control: private, max-age0, no-cache头绕开指纹和缓存机制——但依然享受 Sprockets 从 ES6、ERB 等源文件编译 JS 的能力。一键安装rails g serviceworker:install 快速配置步骤安装过程非常轻量三步完成在Gemfile中加入gem serviceworker-rails执行bundle在项目根目录运行生成器rails g serviceworker:install在 JS 入口中引入 companion 脚本见下一节生成器lib/generators/serviceworker/install_generator.rb会自动完成这些工作生成的文件作用config/initializers/serviceworker.rb路由映射与中间件配置app/assets/javascripts/serviceworker.js.erb空白的 Service Worker 脚本模板含安装/激活示例app/assets/javascripts/serviceworker-companion.js浏览器端注册 SW 的伴侣脚本app/assets/javascripts/manifest.json.erbPWA 网页应用清单Web App Manifestpublic/offline.html离线兜底页面它还会把serviceworker.js和manifest.json追加到预编译列表并在app/views/layouts/application.html.erb的head中自动插入 manifest 链接标签。Importmaps 集成serviceworker-rails 搭配现代 Rails 资产栈的正确姿势这是现代 Rails 用户最关心的问题生成器默认把文件放在app/assets/javascriptsSprockets 目录如果你用Importmapsapp/javascript目录该怎么办官方推荐的迁移方式很简单把生成的serviceworker.js.erb和serviceworker-companion.js从app/assets/javascripts移动到app/javascript在app/javascript/application.js中加入import serviceworker-companion⚠️两个关键注意点不要把serviceworker.js打进主 JS 包。Service Worker 运行在独立于页面的线程中它必须作为单独的文档被请求和注册。如果你的入口文件里写了require_tree .这类全量引入需要把它换成更精确的引用或把serviceworker.js挪到单独的目录。资产清单manifest可以走 Sprockets 预编译manifest 中的图标路径通过image_path助手生成与 Importmaps 无冲突可保留在app/assets下。更妙的是这个 gem 在中间件层面就为非 Sprockets 栈留好了后路原理揭秘Sprockets 与 Rack 双 Handler 的中间件设计serviceworker-rails 的核心是一个 Rack 中间件lib/serviceworker/middleware.rb它在 Rails 启动时由引擎lib/serviceworker/engine.rb自动挂入中间件栈。工作流程路由匹配只处理GET/HEAD请求用你配置的config.serviceworker.routes.draw匹配请求路径例如把/serviceworker.js映射到名为serviceworker.js的资产也支持match /proxied-serviceworker.js nested/asset/serviceworker.js这类显式映射和路径捕获插值。选择 HandlerSprocketsHandlerlib/serviceworker/handlers/sprockets_handler.rb开发环境config.assets.compile为真时实时编译返回生产环境则从public/assets读取预编译文件——这正是不依赖 Sprockets 运行时也能工作的原因。RackHandlerlib/serviceworker/handlers/rack_handler.rb当应用没有启用 Sprockets 资产配置时Handler 选择逻辑会默认切换到它直接用Rack::File从public目录静态返回文件。注入响应头默认附加Cache-Control: private, max-age0, no-cache你还可以通过config.serviceworker.headers[Service-Worker-Allowed] /等方式自定义全局或单条路由的响应头。也就是说用 Sprockets、Importmaps Sprockets 处理 manifest、还是纯静态 public 资产它都能适配——这就是标题里Sprockets 不是唯一答案的底气所在。PWA 体验三件套manifest、离线页与应用图标Service Worker 负责缓存与离线逻辑而完整的 PWA 体验还需要三样东西serviceworker-rails 的生成器已经全部备齐Web App Manifest模板lib/generators/serviceworker/templates/manifest.json内置了应用名称、启动 URL、主题色并自动引用 gem 自带的 13 种尺寸心形图标36px 到 512px见 lib/assets/images/serviceworker-rails/让应用在 Android / iOS 上可安装。离线兜底页public/offline.html配合 SW 的fetch策略在网络失败时展示。图标尺寸可配置config.serviceworker.icon_sizes控制 manifest 中输出的图标列表。验证清单4 步确认你的 Service Worker 已生效 ✅按 README 的测试流程重启应用后用 Chrome / Firefox 打开页面DevTools 中看到页面向/serviceworker.js发起请求Rails 编译并返回你的serviceworker.js.erb内容控制台出现页面与 Service Worker 各自的日志应用的 JS/CSS 资产出现在浏览器的请求/响应缓存中小结serviceworker-rails 用一条中间件 生成器就把 Service Worker 最反直觉的反缓存、固定路径、作用域问题全部解决。无论你坚守 Sprockets 还是拥抱 Importmaps只要记住三条固定路径注册 SW、伴侣脚本进主包、SW 脚本独立不打包就能让现代 Rails 应用轻松拥有离线能力与 PWA 体验 【免费下载链接】serviceworker-railsUse Service Worker with the Rails asset pipeline项目地址: https://gitcode.com/gh_mirrors/se/serviceworker-rails创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
