SvelteKit PWA 项目中动态路由缓存问题的解决方案

问题背景

在使用 SvelteKit 构建 PWA 应用时，开发者经常会遇到动态路由缓存问题。典型表现为：应用首页(/)能正常加载，但动态路由页面如/explore、/posts/x、/users/y等无法正确加载资源，页面显示异常。

问题根源分析

这个问题的核心原因在于 Service Worker 的缓存策略配置不当，特别是对于动态生成页面的处理。当用户访问动态路由时，Service Worker 会尝试从错误的位置加载资源，而不是从基础路径加载。

解决方案详解

1. 基础路径配置

首先需要确保 SvelteKit 配置中正确设置了基础路径：

// svelte.config.js
export default {
  kit: {
    paths: {
      relative: false  // 确保使用绝对路径而非相对路径
    }
  }
}

2. Service Worker 配置优化

对于 SvelteKit PWA 项目，需要特别注意以下几点：

• 动态生成页面排除：所有动态生成页面和 API 调用必须从 Service Worker 拦截中排除
• 预渲染处理：非预渲染页面不会在构建目录(dist)中有对应的 HTML 文件
• 回退策略：需要配置合理的回退策略避免浏览器离线错误页

3. 具体配置示例

// vite.config.ts
export default defineConfig({
  plugins: [
    sveltekit(),
    VitePWA({
      workbox: {
        globPatterns: ['client/**/*.{js,css,png}'],
        navigateFallbackDenylist: [
          // 排除所有动态路由
          /^\/[^/]+\/?$/,
          /^\/[^/]+\/posts\/[^/]+\/?$/,
          /^\/profile\/[^/]+\/?$/,
          /^\/posts\/[^/]+\/?$/,
          /^\/topics\/[^/]+\/?$/
        ],
        runtimeCaching: [
          {
            urlPattern: ({ url, sameOrigin }) => 
              sameOrigin && url.pathname.match(/^\/[^/]+\/?$/),
            handler: 'NetworkFirst',
            options: {
              cacheName: 'dynamic-pages-cache',
              cacheableResponse: { statuses: [200] },
              matchOptions: { ignoreVary: true, ignoreSearch: true }
            }
          }
        ]
      }
    })
  ]
})

4. 常见错误排查

1. 正则表达式问题：确保在 navigateFallbackDenylist 和 runtimeCaching 中使用相同的正则表达式
2. 缓存名称重复：避免为不同路由使用相同的缓存名称
3. 静态资源位置：确保 PWA 图标等静态资源位于项目根目录的 static 文件夹中
4. 错误页面处理：如果重定向到错误页面，确保该页面已被预渲染

最佳实践建议

1. 统一缓存策略：将所有动态路由的逻辑合并到一个 urlPattern 处理器中
2. 开发模式调试：在开发阶段设置 mode: 'development' 以便查看 Workbox 日志
3. 缓存验证：在浏览器开发者工具的 Cache Storage 中定期检查缓存状态
4. 路由测试：对每种类型的动态路由进行完整测试，包括页面刷新后的行为

总结

SvelteKit PWA 项目中的动态路由缓存问题通常源于 Service Worker 配置不当。通过合理设置基础路径、正确排除动态生成页面、优化缓存策略以及仔细调试正则表达式，可以有效地解决这类问题。开发者应当特别注意动态路由与静态资源的不同处理方式，并确保所有关键页面都能在离线状态下正常工作。