Firebase App Check集成Next.js报错：应用未注册问题求助

我按照Firebase官方指南在Next.js（v14）项目中集成Firebase App Check，代码如下：

// firebase/app.js

import { initializeApp } from "firebase/app";
import { initializeAppCheck, ReCaptchaV3Provider } from "firebase/app-check";


const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
  appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
  measurementId: process.env.NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID,
  databaseURL: process.env.NEXT_PUBLIC_DATABASE_URL,
};

export const app = initializeApp(firebaseConfig);

// 避免SSR时出现'document is not defined'错误
if (typeof window !== "undefined") {
  initializeAppCheck(app, {
    provider: new ReCaptchaV3Provider(
      process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY
    ),
    isTokenAutoRefreshEnabled: true,
  });
}

但本地及生产环境运行时均出现以下错误：

POST https://content-firebaseappcheck.googleapis.com/v1/projects/xxx/apps/xxx:exchangeRecaptchaV3Token?key=xxx 400 (Bad Request)

@firebase/app-check: AppCheck: Requests throttled due to 400 error. Attempts allowed again after 00m:02s (appCheck/throttled).

浏览器网络请求返回：

{
  "code": 400,
  "message": "App not registered: 1:123xxxxx.", // 已确认这是正确的Firebase应用ID
  "status": "FAILED_PRECONDITION"
}

无法完成reCAPTCHA验证。我已确认应用在Firebase及Google Cloud控制台的reCAPTCHA Enterprise API网站密钥均配置正确，且同项目的Realtime Database可正常运行。此外，我已在新Firebase项目的空仓库中复现该问题，怀疑是App Check配置遗漏，恳请协助排查解决。

复现仓库：pierre-phil/next.js_firebase_starter

排查解决步骤 #

1. 确认App Check已为目标Web应用启用 #

进入Firebase控制台 → 你的项目 → App Check 页面，检查列表中是否包含你的Web应用：

• 如果未添加，点击“添加应用”，选择Web平台，按照提示完成配置并关联reCAPTCHA Enterprise提供者。
• 如果已添加，确认状态为“已启用”，且提供者是reCAPTCHA Enterprise。

2. 验证reCAPTCHA密钥与Firebase应用的绑定 #

进入Google Cloud控制台 → reCAPTCHA Enterprise → 找到你的站点密钥：

• 查看“关联的Firebase项目”，确认包含当前项目，且对应的Web应用ID与错误信息中的1:123xxxxx完全匹配。
• 若未绑定，编辑密钥配置，添加对应的Firebase项目和应用。

3. 检查Firebase App ID格式是否完整 #

错误信息中的App ID格式为1:xxxxxx，但完整的Firebase Web应用ID应为1:xxxxxx:web:xxxxxx：

• 核对firebaseConfig中的appId是否完整，确保从Firebase控制台复制的是完整的应用ID，而非截断的部分。

4. 确认reCAPTCHA Enterprise API已启用 #

进入Google Cloud控制台 → API和服务 → 库：

• 搜索“reCAPTCHA Enterprise API”，确认该API已启用（若未启用，点击“启用”按钮）。

5. 本地开发域名白名单配置 #

如果是本地环境（如localhost:3000），需在reCAPTCHA密钥的配置中添加允许的域名：

• 编辑reCAPTCHA站点密钥，将localhost、localhost:3000（或你使用的端口）添加到“允许的域名”列表。

6. 调整Next.js中App Check的初始化时机（针对App Router） #

Next.js 14的App Router中，客户端组件的初始化逻辑建议放在useEffect中，确保在客户端完全加载后执行：

// 在客户端组件中使用（比如app/layout.js或单独的客户端组件）
'use client';

import { useEffect } from 'react';
import { app } from '@/firebase/app';
import { initializeAppCheck, ReCaptchaV3Provider } from 'firebase/app-check';

export default function AppCheckInitializer() {
  useEffect(() => {
    initializeAppCheck(app, {
      provider: new ReCaptchaV3Provider(process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY),
      isTokenAutoRefreshEnabled: true,
    });
  }, []);

  return null;
}

然后在根布局中引入这个组件即可。

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