Firebase AppCheck突发403 fetch-status-error报错如何排查

问题相关配置与报错 #

现有AppCheck配置代码如下：

if (process.env.NODE_ENV !== 'development') {
  firebaseConfig.measurementId = process.env.VUE_APP_FIREBASE_APP_ID;
  firebaseConfig.messagingSenderId = process.env.VUE_APP_FIREBASE_MESSAGING_SENDER_ID;
  firebaseConfig.storageBucket = process.env.VUE_APP_FIREBASE_STORAGE_BUCKET;
} else {
  global.self.FIREBASE_APPCHECK_DEBUG_TOKEN = process.env.VUE_APP_FIREBASE_APPCHECK_DEBUG_TOKEN;
}
// firebase utils
const fbApp = initializeApp(firebaseConfig);

const nodeEnv = process.env.NODE_ENV;
const fbAnalytics = !(nodeEnv === 'test' || nodeEnv === 'development') ? getAnalytics() : null;
const appCheck = initializeAppCheck(fbApp, {
  provider: new ReCaptchaV3Provider(process.env.VUE_APP_RECAPTCHA_SITE_KEY),
  isTokenAutoRefreshEnabled: process.env.NODE_ENV === 'production', // refresh app tokens as needed?
});

故障现象：配置上周可正常运行，本周开始持续返回403错误，当前搭配Firebase emulator使用，所有环境变量已正确注入前端。
报错日志：

[2022-06-24T04:20:29.116Z] @firebase/firestore: Firestore (9.8.4): 无法连接Cloud Firestore后端，累计1次连接失败。最近一次错误：FirebaseError: [code=unknown]: 获取auth token失败：AppCheck: 请求服务端返回HTTP错误状态码，HTTP status: 403. (appCheck/fetch-status-error)。该提示通常表示当前设备网络连接异常，客户端将运行在离线模式，直到成功连接后端为止。

常见故障原因与修复方式 #

• 开发环境未正确连接AppCheck Emulator
  这是搭配Emulator使用时最高发的问题。当前代码中没有调用connectAppCheckEmulator方法，开发环境下AppCheck SDK会默认向生产环境的AppCheck校验接口发请求，生产环境无法识别Emulator上下文的请求，会直接返回403。
  修复方式：在initializeAppCheck调用之后，增加开发环境的Emulator连接逻辑，示例：

  if (process.env.NODE_ENV === 'development') {
    connectAppCheckEmulator(fbApp, 'localhost', 5001); // 端口替换为本地AppCheck Emulator实际运行端口
  }
  

  如果本地开发不需要校验AppCheck，也可以直接在test/development环境跳过AppCheck初始化，减少不必要的鉴权逻辑。

• Debug Token失效或未注册
  开发环境使用的VUE_APP_FIREBASE_APPCHECK_DEBUG_TOKEN必须手动添加到Firebase控制台AppCheck板块的调试令牌列表中才会生效。如果上周使用的临时令牌被清理、本地生成了新的调试令牌未同步到控制台、或者切换了Firebase项目未更换对应项目的令牌，都会触发403。
  排查方式：打开浏览器开发者工具控制台，AppCheck初始化时会打印当前生效的debug token，复制该值到Firebase控制台核对，不存在则新增，失效则删除旧令牌后重新添加。
  额外注意：Firebase JS SDK 9.x版本存在debug token读取时序问题，global.self.FIREBASE_APPCHECK_DEBUG_TOKEN的赋值必须写在所有Firebase相关import语句之前，否则SDK读取不到自定义token，会自动生成随机的临时token，必然校验失败。

• reCAPTCHA V3配置不匹配
  首先核对环境变量中的VUE_APP_RECAPTCHA_SITE_KEY和Firebase控制台AppCheck中登记的reCAPTCHA V3站点密钥完全一致，如果密钥被重置、或者误填了reCAPTCHA V2的密钥，会直接校验失败。
  其次检查reCAPTCHA后台的域名白名单配置，确认本地开发地址（localhost、127.0.0.1）、线上部署地址都在允许列表中，近期如果调整过白名单规则误删了本地地址，也会触发403。

• AppCheck强制模式开启
  如果近期在Firebase控制台将AppCheck从「监控模式」切换为「强制模式」，所有未通过校验的请求会被直接拦截返回403，而监控模式下只会记录日志不会拦截请求，就会出现“上周还能用，这周突然报错”的现象。
  排查方式：进入Firebase控制台AppCheck设置页，查看Firestore等对应服务的enforcement状态，先切回监控模式确认请求是否恢复，再逐步定位token校验失败的根因。

• 本地缓存或SDK版本bug
  你当前使用的Firebase SDK 9.8.4版本存在多个已知的AppCheck debug模式bug，可能出现token缓存异常不刷新的问题。可以先清空浏览器站点缓存、Service Worker缓存，硬刷新页面重试；如果仍未解决，升级Firebase JS SDK到9.14及以上的稳定版本即可修复相关问题。
  另外你当前配置中开发环境下isTokenAutoRefreshEnabled为false，如果本地缓存的token过期，不会自动刷新新token，也会持续返回403，开发环境可以将该值临时设为true，避免token过期导致的问题。

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