Firebase App Check Web客户端接入报错无法正常工作

你遇到的两类报错本质是App Check校验流程未跑通，按以下优先级逐一排查即可： #

前端reCAPTCHA初始化失败（对应appCheck/recaptcha-error报错） #

这个错误出在前端侧reCAPTCHA加载或执行校验阶段，常见原因及对应解决方法：

• 密钥配置错误
  代码中ReCaptchaEnterpriseProvider传入的参数必须是reCAPTCHA Enterprise的网站类型站点密钥，不能填reCAPTCHA服务端密钥、普通版reCAPTCHA v2/v3密钥、Firebase Web应用的apiKey。创建站点密钥时，允许域名列表必须覆盖你实际访问前端的所有域名，本地调试需添加localhost、127.0.0.1，域名配置不需要带端口号。
• 初始化顺序错误
  App Check必须在Firestore、Storage等所有Firebase业务服务之前初始化，否则业务服务实例拿不到合法App Check令牌，直接触发校验失败。正确初始化顺序参考：

  // 第一步：初始化Firebase核心实例
  const firebaseApp = initializeApp(firebaseConfig);
  // 第二步：初始化App Check
  const appCheck = initializeAppCheck(firebaseApp, {
    provider: new ReCaptchaEnterpriseProvider("你的reCAPTCHA Enterprise站点密钥"),
    isTokenAutoRefreshEnabled: true
  });
  // 第三步：初始化Firestore、Storage等业务服务
  const db = getFirestore(firebaseApp);
  const storage = getStorage(firebaseApp);
  

• 站点CSP策略拦截reCAPTCHA资源
  如果你的站点配置了内容安全策略（CSP），必须将reCAPTCHA依赖的资源域名加入白名单，否则脚本加载失败直接报错：
  • 脚本源白名单添加https://www.google.com、https://www.gstatic.com
  • 帧源白名单添加https://www.google.com

后端校验返回403（对应appCheck/fetch-status-error HTTP 403报错） #

这个错误代表前端已经拿到reCAPTCHA返回的凭证，但发给Firebase后端校验时被判定为非法请求，常见原因及对应解决方法：

• 强制校验规则缓存延迟
  刚在Firebase控制台开启Storage、Firestore的App Check强制校验时，规则最长需要15分钟才能在全球边缘节点同步生效，期间会随机出现403报错，等待同步完成后重试即可。
• 密钥与项目不匹配
  前端使用的reCAPTCHA Enterprise站点密钥，必须和当前Firebase项目绑定的Google Cloud项目下创建的密钥一致，不能跨项目使用密钥。可以在Firebase控制台App Check设置页，找到对应Web应用，核对绑定的站点密钥和前端代码中填入的密钥完全一致。
• 本地调试未配置调试令牌
  本地开发环境默认不会被reCAPTCHA判定为可信来源，需要在Firebase控制台App Check板块生成调试令牌，开发环境下使用调试令牌初始化提供者，否则本地发起的请求会被直接拦截返回403。
• 令牌TTL配置异常
  如果自定义过App Check令牌的有效期，不要将TTL设置为小于5分钟，否则会出现令牌还未发送到后端就已过期的问题，无特殊需求保持默认1小时TTL即可。

快速定位方法 #

初始化App Check后添加以下代码手动触发令牌获取，根据返回结果快速定位问题层：

import { getToken } from "firebase/app-check";
getToken(appCheck)
  .then(res => console.log("App Check令牌获取成功", res.token))
  .catch(err => console.error("令牌获取失败", err));

如果能正常拿到JWT格式的长字符串令牌，说明前端reCAPTCHA流程正常，问题出在后端规则同步或密钥绑定层面；如果这一步直接抛出异常，优先排查前端侧配置问题。

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