如何将Next-pwa数据缓存策略从NetworkOnly改为CacheFirst

next-pwa 默认对API请求、Next.js 内置数据拉取请求采用NetworkOnly策略，直接修改插件顶层配置参数无法覆盖默认规则，需通过自定义runtimeCaching规则实现，具体操作如下：

正确配置示例 #

打开项目根目录的next.config.js/next.config.mjs，在next-pwa初始化参数中添加自定义runtimeCaching规则，注意自定义接口规则要放在规则列表最前（规则按从上到下优先级匹配，先命中先生效）：

const withPWA = require('next-pwa')({
  dest: 'public',
  register: true,
  skipWaiting: true,
  runtimeCaching: [
    // 接口缓存规则（优先匹配）
    {
      urlPattern: ({ url, request }) => {
        // 仅匹配同源GET请求，避免缓存写操作
        const isGetRequest = request.method === 'GET'
        const isSameOrigin = url.origin === self.location.origin
        // 匹配两类接口路径：自定义/api前缀接口、Next.js内置/_next/data数据拉取接口
        const isApiPath = url.pathname.startsWith('/api/') || url.pathname.startsWith('/_next/data/')
        return isGetRequest && isSameOrigin && isApiPath
      },
      handler: 'CacheFirst',
      options: {
        cacheName: 'api-data-cache',
        expiration: {
          maxEntries: 120,
          maxAgeSeconds: 12 * 60 * 60 // 缓存有效期可根据业务需求调整，单位为秒
        },
        cacheableResponse: {
          statuses: [0, 200] // 仅缓存正常响应
        }
      }
    },
    // 保留默认静态资源、跨域请求缓存规则
    {
      urlPattern: /\.(?:png|jpg|jpeg|svg|gif|webp|css|js|woff2?)$/,
      handler: 'CacheFirst',
      options: {
        cacheName: 'static-assets',
        expiration: {
          maxEntries: 500,
          maxAgeSeconds: 30 * 24 * 60 * 60
        }
      }
    },
    {
      urlPattern: /^https?.*/,
      handler: 'NetworkFirst',
      options: {
        cacheName: 'other-resources',
        networkTimeoutSeconds: 10,
        expiration: {
          maxEntries: 200
        }
      }
    }
  ]
})

const nextConfig = {
  // 项目原有Next.js配置项
}

module.exports = withPWA(nextConfig)

常见不生效的排查点 #

• 规则顺序错误：如果把通配所有路径的规则放在接口规则前面，接口请求会先被通配规则命中，CacheFirst配置不会生效
• 旧Service Worker未清理：配置修改后，需要打开浏览器DevTools，进入「Application - Service Workers」面板，点击「Unregister」注销旧的Service Worker，随后硬刷新页面（Ctrl+Shift+R / Cmd+Shift+R）加载新的SW脚本
• 匹配规则漏了Next内置数据路径：如果项目用getServerSideProps、getStaticProps或App Router的数据拉取，请求默认走/_next/data/路径，没把这个路径加入匹配规则的话，这部分请求依然会走默认NetworkOnly
• 错误缓存非GET请求：CacheFirst策略仅适用于GET类读请求，不要给POST、PUT、DELETE等写操作请求配置缓存，会导致业务逻辑异常

生效验证 #

配置生效后，打开DevTools的「Application - Cache Storage」面板，可以看到自定义的api-data-cache缓存库；切到Network面板查看接口请求，请求的发起者会显示为Service Worker，断网状态下刷新页面也能正常加载之前缓存过的接口数据。

内容的提问来源于stack exchange，提问作者dreeeeeedd