Next.js 13 App目录下基于next-pwa实现PWA自定义离线页面

先搞懂next-pwa的offlineFallback选项 #

这个选项是用来开启离线回退机制的：当用户离线访问应用，且请求的资源不在缓存里时，Service Worker会自动返回你指定的离线页面，替代浏览器默认的离线错误页。

实现步骤 #

1. 创建自定义离线页面

在Next.js 13的App目录下，新建app/offline/page.js文件，编写你的离线页面内容，示例如下：

export default function OfflinePage() {
  return (
    <div style={{ 
      display: 'flex', 
      flexDirection: 'column', 
      alignItems: 'center', 
      justifyContent: 'center', 
      height: '100vh',
      padding: '2rem',
      textAlign: 'center'
    }}>
      <h1>哎呀，你离线了</h1>
      <p>请检查网络连接，稍后再试</p>
      <button onClick={() => window.location.reload()} style={{ 
        marginTop: '1rem',
        padding: '0.5rem 1rem',
        cursor: 'pointer'
      }}>
        重新加载
      </button>
    </div>
  )
}

你可以完全自定义这个页面的样式、文案和交互逻辑。

2. 配置next.config.js

在项目根目录的next.config.js中，配置next-pwa的离线回退参数：

const withPWA = require('next-pwa')({
  dest: 'public', // Service Worker文件的输出目录
  register: true, // 自动注册Service Worker
  skipWaiting: true, // 立即激活新的Service Worker，无需用户刷新
  offlineFallback: true, // 启用离线回退功能
  fallback: {
    document: '/offline' // 指定离线时回退的页面路由
  },
  // 可选：配置缓存规则，确保离线页面被缓存
  runtimeCaching: [
    {
      urlPattern: /^https?.*/,
      handler: 'NetworkFirst',
      options: {
        cacheName: 'app-cache',
        expiration: {
          maxEntries: 100
        }
      }
    }
  ]
})

module.exports = withPWA({
  // Next.js基础配置
  reactStrictMode: true,
  // 若要导出静态站点，可开启此选项
  // output: 'export'
})

关键说明：

• offlineFallback: true必须开启，否则离线回退不生效
• fallback.document要严格对应你创建的离线页面路由（这里是/offline）

3. 验证离线功能

1. 构建生产版本并启动服务：

   npm run build && npm run start
   

2. 打开浏览器访问应用
3. 打开开发者工具（F12），切换到Application标签，在Service Workers板块勾选Offline选项
4. 刷新页面，此时应该显示你自定义的离线页面

注意事项 #

• 确保使用兼容Next.js 13 App目录的next-pwa版本，建议安装最新版：npm install next-pwa@latest
• 离线页面尽量不要依赖外部CDN资源（如第三方字体、图片），如果必须使用，要确保这些资源被Service Worker缓存
• 修改离线页面后，需要重新构建项目，并且在浏览器中刷新页面（或跳过Service Worker等待）才能生效

内容的提问来源于stack exchange，提问作者Manas S. Roy