如何配置Workbox实现SPA离线非首页路由回退到/index.html

嗨，我之前也碰到过一模一样的问题！你提到的navigationFallback是GenerateSW插件专属的参数，而InjectManifest是让你自定义Service Worker逻辑的，直接加这个参数肯定会报错。别慌，咱们通过在自定义SW文件里配置Workbox的路由策略就能轻松搞定。

核心原因 #

单页应用的非首页路由都是前端路由，当你离线刷新/page1这类路径时，浏览器会把它当成真实的资源请求去查找，缓存里没有对应的文件就会返回404。咱们要做的就是让所有导航类的HTML请求，在离线状态下自动回退到预缓存的index.html。

具体配置步骤 #

1. 确保Webpack的InjectManifest插件配置正确

先确认你的webpack配置里，InjectManifest指向了自定义的Service Worker源文件，比如sw-src.js：

const { InjectManifest } = require('workbox-webpack-plugin');

module.exports = {
  // 你的其他Webpack配置（entry、output等）
  plugins: [
    new InjectManifest({
      swSrc: './src/sw-src.js', // 自定义SW的源文件路径
      swDest: 'service-worker.js', // 最终生成的SW文件名
      // 可选：排除不需要预缓存的文件
      // exclude: [/\.map$/, /asset-manifest\.json$/],
    }),
  ],
};

2. 在自定义SW文件中配置导航回退规则

打开你的sw-src.js，加入以下代码——用workbox-routing和workbox-strategies来处理导航请求：

import { precacheAndRoute } from 'workbox-precaching';
import { registerRoute } from 'workbox-routing';
import { NetworkFirst } from 'workbox-strategies';

// 处理Webpack注入的预缓存清单，这一步必须有！
precacheAndRoute(self.__WB_MANIFEST);

// 配置导航回退逻辑
registerRoute(
  // 匹配用户的导航请求（刷新页面、直接输入URL等场景）
  ({ mode }) => mode === 'navigate',
  // 使用NetworkFirst策略：优先尝试网络请求，失败则用缓存
  new NetworkFirst({
    cacheName: 'html-navigation-cache',
    plugins: [
      {
        // 当网络请求失败（离线）时，返回预缓存的index.html
        handlerDidError: async () => {
          return await caches.match('/index.html');
        },
      },
    ],
  })
);

关键细节说明 #

• self.__WB_MANIFEST是Webpack通过InjectManifest自动注入的预缓存资源数组，调用precacheAndRoute会把这些资源缓存起来，包括你的index.html。
• mode === 'navigate'确保我们只处理用户的导航请求，不会影响JS、CSS等静态资源的缓存策略。
• 如果你的index.html不在根目录（比如部署在/app/下），记得把/index.html改成对应的路径，比如/app/index.html。
• 也可以用StaleWhileRevalidate策略，优先用缓存再后台更新，适合对实时性要求不高的场景，把上面的NetworkFirst换成它就行。

这样配置后，不管你离线时刷新哪个前端路由，都会返回index.html，SPA的路由系统就能正常接管页面了！

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