next-offline项目离线刷新页面出现Internal Server Error求助

我之前也碰到过类似的next-offline离线场景问题，来帮你梳理下解决方案！

问题根源分析 #

你遇到的情况核心原因是：Next.js的SSR（服务器端渲染）机制。当你离线刷新PAGE 2时，Next.js会尝试在服务器端执行页面的getServerSideProps（或getInitialProps），这时候发起的API请求在离线状态下直接失败，服务器无法生成正常的页面HTML，所以返回了Internal Server Error。而在线时客户端导航是SPA模式，不会触发服务器端渲染，直接用客户端路由加载页面，所以没问题。

具体解决方案 #

1. 给服务器端API请求添加错误捕获与降级处理

首先要确保即使API请求失败，服务器端也能返回合法的页面props，让组件可以正常渲染。比如在PAGE 2的getServerSideProps里添加try/catch：

export async function getServerSideProps() {
  let todoData = null;
  try {
    const res = await fetch('https://jsonplaceholder.typicode.com/todos/1');
    todoData = await res.json();
  } catch (err) {
    // 离线或网络错误时，返回降级数据
    todoData = {
      id: 1,
      title: "离线模式下的默认待办",
      completed: false
    };
    // 如果不需要展示数据，也可以返回null，组件里处理空状态
  }

  return {
    props: { todoData }
  };
}

这样即使离线时服务器端请求失败，也能返回合法的props，页面就能正常渲染，不会出现500错误。

2. 配置next-offline的Service Worker，预缓存页面与API响应

接下来要让Service Worker缓存页面和API数据，确保离线时刷新能直接用缓存内容。修改你的next.config.js，调整workbox的缓存策略：

const withOffline = require('next-offline');

module.exports = withOffline({
  workboxOpts: {
    runtimeCaching: [
      // 缓存API请求，优先用缓存再后台更新
      {
        urlPattern: /^https:\/\/jsonplaceholder\.typicode\.com\/.*/,
        handler: 'StaleWhileRevalidate',
        options: {
          cacheName: 'jsonplaceholder-api-cache',
          cacheableResponse: {
            statuses: [200]
          }
        }
      },
      // 缓存页面，优先尝试网络，失败则用缓存
      {
        urlPattern: /^\/.*/,
        handler: 'NetworkFirst',
        options: {
          cacheName: 'nextjs-page-cache',
          // 配置缓存有效期，按需调整
          expiration: {
            maxAgeSeconds: 7 * 24 * 60 * 60 // 7天
          }
        }
      }
    ]
  }
});

• StaleWhileRevalidate策略：离线时直接返回缓存的API数据，在线时后台更新缓存，保证数据新鲜度。
• NetworkFirst策略：页面优先尝试网络请求，失败则用缓存的页面内容，刚好适配你离线刷新的场景。

3. 客户端组件添加空状态/错误处理

最后，在PAGE 2的组件里处理数据为空或降级的情况，给用户友好的提示：

export default function Page2({ todoData }) {
  if (!todoData) {
    return <div>离线模式下暂时无法加载数据，请稍后再试</div>;
  }

  return (
    <div>
      <h1>PAGE 2</h1>
      <p>Todo Title: {todoData.title}</p>
    </div>
  );
}

验证步骤 #

按照上面的配置修改后，重新构建并部署项目：

1. 在线状态下导航到PAGE 2，让Service Worker缓存页面和API数据
2. 切换到离线模式，刷新PAGE 2，现在应该能正常显示页面（用降级数据或缓存的API数据）

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