Next.js App Router集成Firebase AppCheck初始化错误求助

核心问题原因 #

Next.js App Router 默认使用服务器组件，代码会在服务端执行，而 Firebase AppCheck（尤其是 reCAPTCHA 依赖）需要浏览器环境（window/document 对象），直接在服务器组件中初始化会触发环境不兼容错误。

具体实现步骤 #

1. 创建专属客户端组件处理 AppCheck 初始化 #

在项目中新建一个客户端组件（比如 components/FirebaseAppCheck.tsx），必须添加 'use client' 指令标记为客户端组件：

'use client';

import { useEffect } from 'react';
import { initializeAppCheck, ReCaptchaV3Provider } from 'firebase/app-check';
import { app } from '@/lib/firebase/config'; // 导入已初始化的 Firebase App 实例

export default function FirebaseAppCheck() {
  useEffect(() => {
    // 仅在客户端环境执行初始化
    if (typeof window !== 'undefined') {
      // 开发模式启用 Debug Token
      if (process.env.NODE_ENV === 'development') {
        window.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
        console.log('AppCheck Debug Token enabled');
      }

      // 初始化 AppCheck
      initializeAppCheck(app, {
        provider: new ReCaptchaV3Provider('你的 reCAPTCHA v3 密钥'),
        isTokenAutoRefreshEnabled: true, // 开启令牌自动刷新
      });
    }
  }, []);

  // 组件无需渲染任何内容
  return null;
}

2. 在根布局中引入该客户端组件 #

打开 app/layout.tsx（或项目的根布局文件），导入并添加这个组件：

import FirebaseAppCheck from '@/components/FirebaseAppCheck';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="zh-CN">
      <body>
        {/* 引入 AppCheck 初始化组件 */}
        <FirebaseAppCheck />
        {children}
      </body>
    </html>
  );
}

3. 验证配置 #

• 确保你的 Firebase App 实例（app）已经正确初始化，且只初始化一次（建议放在单独的 firebase/config.ts 文件中）。
• 替换代码中的 你的 reCAPTCHA v3 密钥 为 Firebase 控制台获取的实际密钥。
• 开发模式下，浏览器控制台会输出 AppCheck Debug Token enabled，同时 Firebase 控制台会生成 Debug Token，将其添加到 AppCheck 的允许列表即可正常测试。

关键注意事项 #

• 必须使用客户端组件：'use client' 指令是核心，确保所有依赖浏览器环境的代码只在客户端执行。
• 禁止在服务器组件中初始化：任何涉及 window/document 或 reCAPTCHA 的代码都不能放在服务器组件里。
• Debug Token 顺序：window.FIREBASE_APPCHECK_DEBUG_TOKEN 必须在 initializeAppCheck 之前设置，且仅在开发环境启用。

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