React Web集成Firebase AppCheck(reCaptchaV3)失效报错排查

你当前代码的核心问题是Firebase SDK版本混用冲突：使用compat兼容模式初始化Firebase App实例，却引入模块化v9版本的AppCheck相关方法做初始化，两个模式的实例不互通，直接触发初始化失败。

修复方案（二选一即可） #

方案1：全量切换为v9模块化SDK（官方推荐） #

将所有compat路径的引入替换为模块化v9写法，保证实例类型统一，参考代码如下：

import { initializeApp } from "firebase/app";
import { getAuth } from "firebase/auth";
import { getFirestore, collection } from "firebase/firestore";
import { getStorage } from "firebase/storage";
import { initializeAppCheck, ReCaptchaV3Provider } from "firebase/app-check";

const firebaseConfig = {
    apiKey: process.env.REACT_APP_FIREBASE_API_KEY,
    authDomain: process.env.REACT_APP_FIREBASE_AUTH_DOMAIN,
    databaseURL: process.env.REACT_APP_FIREBASE_DATABASE_URL,
    projectId: process.env.REACT_APP_FIREBASE_PROJECT_ID,
    storageBucket: process.env.REACT_APP_FIREBASE_STORAGE_BUCKET,
    messagingSenderId: process.env.REACT_APP_FIREBASE_MESSAGING_SENDER_ID,
    appId: process.env.REACT_APP_FIREBASE_APP_ID
};

const app = initializeApp(firebaseConfig);

// 本地开发开启调试令牌，上线前删除
if (process.env.NODE_ENV === 'development') {
    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
}

const appCheck = initializeAppCheck(app, {
    provider: new ReCaptchaV3Provider(process.env.REACT_APP_APP_CHECK_RECAPTCHA_SITEKEY),
    isTokenAutoRefreshEnabled: true
});

const firestore = getFirestore(app);
const storage = getStorage(app, "gs://sftc-development.appspot.com");
const auth = getAuth(app);

export const database = {
    usersRef: collection(firestore, 'user'),
    portfolioRef: collection(firestore, 'portfolio'),
    projectTitleRef: collection(firestore, 'projectTitle'),
    audioRef: collection(firestore, 'audio'),
    videoRef: collection(firestore, 'video'),
    imageRef: collection(firestore, 'image'),
    ascensionRef: collection(firestore, 'ascensionNumber')
};
export { storage, auth, appCheck, app };
export default app;

注意：切换全量模块化后，项目中其他调用Firebase服务的业务代码也要同步替换为v9模块化写法，不能继续使用compat模式的链式调用。

方案2：保留compat模式，使用兼容版AppCheck #

如果暂时不想重构现有业务的compat写法，直接替换AppCheck的引入和初始化逻辑即可，原有业务代码无需改动：

import firebase from "firebase/compat/app";
import "firebase/compat/auth"
import "firebase/compat/firestore"
import "firebase/compat/storage"
// 引入compat版本的app-check包
import "firebase/compat/app-check";

const app = firebase.initializeApp({
    apiKey: process.env.REACT_APP_FIREBASE_API_KEY,
    authDomain: process.env.REACT_APP_FIREBASE_AUTH_DOMAIN,
    databaseURL: process.env.REACT_APP_FIREBASE_DATABASE_URL,
    projectId: process.env.REACT_APP_FIREBASE_PROJECT_ID,
    storageBucket: process.env.REACT_APP_FIREBASE_STORAGE_BUCKET,
    messagingSenderId: process.env.REACT_APP_FIREBASE_MESSAGING_SENDER_ID,
    appId: process.env.REACT_APP_FIREBASE_APP_ID
})

// 本地开发开启调试令牌，上线前删除
if (process.env.NODE_ENV === 'development') {
    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
}

// compat模式下初始化AppCheck
const appCheck = firebase.appCheck();
appCheck.activate(
    process.env.REACT_APP_APP_CHECK_RECAPTCHA_SITEKEY,
    true
);

const firestore = app.firestore();
export const database = {
    usersRef: firestore.collection('user'),
    portfolioRef: firestore.collection('portfolio'),
    projectTitleRef: firestore.collection('projectTitle'),
    audioRef: firestore.collection('audio'),
    videoRef: firestore.collection('video'),
    imageRef: firestore.collection('image'),
    ascensionRef: firestore.collection('ascensionNumber')
};
export const storage = app.storage("gs://sftc-development.appspot.com");
export const auth = app.auth();
export default app;

其他常见问题排查 #

修复SDK混用问题后如果仍不生效，按以下顺序检查：

• 校验密钥一致性：确认代码中填入的reCaptchaV3站点密钥和Firebase控制台AppCheck配置中登记的密钥完全一致，不要混淆服务端密钥、其他Firebase配置密钥
• 校验域名白名单：确认当前访问域名（本地调试为localhost、线上为业务域名）同时加入了reCaptcha控制台的允许域名列表、Firebase AppCheck的授权域名列表
• 校验环境变量生效：React项目中REACT_APP_开头的环境变量修改后必须重启开发服务器才能生效，热更新不会加载新的环境变量值
• 校验初始化时序：确保AppCheck初始化逻辑在所有Firebase服务调用（登录、数据库读写、存储上传）之前执行，避免服务请求先于AppCheck拿到合法令牌
• 校验控制台配置：确认Firebase控制台中AppCheck的reCaptchaV3 provider已经处于启用状态，不是保存了配置但未开启强制校验/未生效状态

报错截图 #

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