iOS 18下PWA独立模式Service Worker/CacheStorage缓存失效求助

• 检查 Manifest 文件的 iOS 18 适配性

  • 确认 start_url 为绝对路径且与应用部署路径完全匹配，避免多余查询参数（必要初始化参数除外），iOS 18 对该字段的校验更严格。
  • 确保 display 属性设置为 standalone 或 fullscreen，iOS 18 可能调整了 minimal-ui 模式下的 Service Worker 行为。
  • 验证 scope 属性覆盖所有需缓存的资源路径，防止因范围限制导致 Service Worker 无法拦截请求。

• 排查 Service Worker 注册与激活流程

  • 开启 iOS 18 Safari 开发者工具（需启用手机端 Web 检查器），在 Application -> Service Workers 面板查看注册、激活状态及错误信息。
  • 注册 Service Worker 时使用绝对路径，iOS 18 对相对路径解析规则可能有变化。
  • 若应用部署在子路径下，确保 Service Worker 文件的响应头包含 Service-Worker-Allowed，避免注册失败。

• 适配 Workbox 6.5.4 缓存逻辑

  • 检查缓存策略配置，iOS 18 可能对 CacheFirst、StaleWhileRevalidate 等策略的触发条件有调整，避免过于激进的缓存规则。
  • 确认 Workbox 预缓存清单包含所有离线所需资源，包括 manifest 中的图标、启动页等静态资源——iOS 18 可能不再自动缓存这些资源，需手动加入预缓存。
  • 避免在 Service Worker 初始化阶段执行耗时操作，iOS 18 可能缩短了启动超时时间，导致缓存逻辑未完成就被终止。

• 验证独立模式特殊限制

  • 检查应用是否存在跨域资源请求，iOS 18 独立模式下可能新增跨域缓存限制，需确保跨域资源配置正确的 CORS 响应头，Service Worker 能正常处理缓存。
  • 测试 Safari 浏览器直接访问（非独立模式）是否正常缓存，若正常则说明独立模式有特殊限制，可通过 navigator.standalone 或 display-mode 媒体查询添加针对性逻辑。

• 调试与日志定位

  • 在 Service Worker 代码中添加 console.log 日志，通过 Safari 开发者工具控制台查看缓存流程执行情况，定位未执行的环节。
  • 使用 caches.open()、caches.keys() 等 API 手动检查 CacheStorage 条目，确认资源是否被正确缓存。

内容的提问来源于stack exchange，提问作者Jérôme Morlon