如何配置Nuxt SSR应用的Firebase离线认证并解决离线报错？

问题根因 #

• 离线状态下Firebase Auth SDK初始化时，会尝试对本地缓存的登录态发起网络校验，请求失败后抛出的auth/network-request-failed错误为未捕获的Promise rejection，会冒泡到全局事件循环，阻塞页面主交互逻辑，导致导航、菜单等组件无响应
• 未显式开启Auth SDK的本地持久化策略，离线时无法直接从本地存储读取已登录用户态，反复触发网络请求
• 现有Auth状态处理逻辑未补充异常捕获，拉取用户资料、读取token的异步流程在断网时抛出的错误未被处理，进一步阻塞主线程

具体配置修改步骤 #

1. 补充全局错误捕获，阻止未处理的Auth网络错误阻塞页面 #

• 在客户端插件层添加unhandledrejection事件监听，过滤离线场景下的Firebase Auth网络类错误，阻止报错冒泡到全局事件循环
  编写插件文件plugins/firebase-global-error.client.js：

  export default () => {
    window.addEventListener('unhandledrejection', (event) => {
      // 拦截离线引发的Auth网络错误，避免阻塞页面交互
      if (event.reason?.code === 'auth/network-request-failed') {
        event.preventDefault()
      }
    })
  }
  

  插件会在客户端自动加载，无需手动在nuxt.config.js中注册。

2. 显式开启Auth本地持久化，支持离线读取登录态 #

• 在nuxt.config.js的Firebase Auth服务配置中，指定持久化策略为本地模式，让Auth SDK在断网时可直接从IndexedDB读取已缓存的用户登录状态，无需发起网络校验
  修改后的Firebase Auth配置：

  // nuxt.config.js 中的firebase配置段
  firebase: {
    config: {
      // 保持原有公开配置不变
    },
    services: {
      auth: {
        ssr: true,
        // 新增：指定本地持久化策略，支持离线状态读取登录态
        persistence: 'local',
        initialize: {
          onAuthStateChangedAction: 'onAuthStateChangedAction'
        }
      }
    }
  }
  

3. 优化Auth状态处理逻辑，补充全链路异常捕获 #

• 对拉取用户资料、读取身份token的异步流程增加异常捕获，离线时直接沿用本地缓存的用户数据，不强制等待网络请求返回
  修改store/index.js中的onAuthStateChangedAction逻辑：

  async onAuthStateChangedAction({ dispatch, commit }, { authUser }) {
    // 无有效登录态时直接清空本地用户信息
    if (!authUser) {
      return commit(MUTATION_TYPE.REMOVE_USER)
    }
  
    // 拉取用户资料时补充catch捕获，避免未处理的Promise阻塞
    dispatch('getUser', authUser).catch((err) => {
      // 离线拉取失败时，直接使用本地缓存的用户数据即可
      console.warn('离线拉取用户资料失败，启用本地缓存', err)
    })
  
    // 客户端环境下优先从当前Auth实例读取有效token
    if (process.browser && authUser) {
      try {
        const token = await authUser.getIdToken()
        commit(MUTATION_TYPE.SET_TOKEN, token)
      } catch (err) {
        // 离线时无法获取最新token，则沿用本地存储的旧token
        if (localStorage.token) {
          commit(MUTATION_TYPE.SET_TOKEN, localStorage.token)
        }
      }
    }
  }
  

4. 优化PWA Workbox配置，确保离线Auth资源缓存生效 #

• 调整nuxt.config.js中的Workbox配置，确保Service Worker立即接管页面，同时对Firebase Auth的接口请求添加离线缓存策略，减少不必要的网络请求
  修改后的PWA Workbox配置：

  // nuxt.config.js 中的pwa配置段
  pwa: {
    // 保持原有manifest、meta、config配置不变
    workbox: {
      importScripts: ['/firebase-auth-sw.js'],
      dev: process.env.NODE_ENV === 'development',
      // 新增：确保Service Worker立即生效，避免等待阻塞页面
      skipWaiting: true,
      clientsClaim: true,
      // 新增：为Firebase Auth接口添加离线缓存策略
      runtimeCaching: [
        {
          urlPattern: /^https:\/\/identitytoolkit\.googleapis\.com\/.*/i,
          handler: 'StaleWhileRevalidate',
          options: {
            cacheName: 'firebase-auth-cache',
            expiration: {
              maxEntries: 10,
              maxAgeSeconds: 60 * 60 * 24 * 30
            }
          }
        }
      ]
    }
  }
  

注意：确认项目public目录下的firebase-auth-sw.js为官方提供的Auth离线同步脚本，无需额外自定义修改，该脚本会在Service Worker层面同步本地Auth缓存，避免离线时跨页面登录状态不一致。

验证效果 #

完成以上配置后：

• 离线状态下Auth SDK会直接从本地IndexedDB读取已登录的用户状态，不会反复发起网络校验请求
• 所有离线引发的Auth网络错误都会被全局捕获，不会冒泡到主线程阻塞页面交互（如汉堡菜单点击、导航跳转等）
• Auth状态会通过Service Worker在离线场景下保持同步，不会出现登录状态丢失的问题

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