如何在Next.js13.4 App目录开发环境用ReactFire配置App Check

核心前提 #

Next.js 13.4 App目录下的组件默认是服务器组件，无法访问浏览器的window对象，而Firebase App Check的初始化依赖客户端环境。因此所有涉及Firebase/App Check的逻辑必须放在标记了'use client';的客户端组件中执行。

解决方案步骤 #

1. 基础初始化方案（无需ReactFire） #

步骤1：创建Firebase配置文件

// firebase/config.ts
export const firebaseConfig = {
  apiKey: "你的API_KEY",
  authDomain: "你的AUTH_DOMAIN",
  projectId: "你的PROJECT_ID",
  storageBucket: "你的STORAGE_BUCKET",
  messagingSenderId: "你的SENDER_ID",
  appId: "你的APP_ID",
  measurementId: "你的MEASUREMENT_ID"
};

步骤2：编写客户端组件初始化App Check

// components/FirebaseAppCheck.tsx
'use client';

import { useEffect } from 'react';
import { initializeApp } from 'firebase/app';
import { initializeAppCheck, ReCaptchaV3Provider, isSupported } from 'firebase/app-check';
import { firebaseConfig } from '../firebase/config';

export default function FirebaseAppCheck() {
  useEffect(() => {
    const initAppCheck = async () => {
      // 双重确保仅在客户端环境执行
      if (typeof window !== 'undefined') {
        const app = initializeApp(firebaseConfig);
        const supported = await isSupported();
        
        if (supported) {
          initializeAppCheck(app, {
            provider: new ReCaptchaV3Provider('你的ReCaptcha V3站点密钥'),
            // 开发模式下启用令牌自动刷新
            isTokenAutoRefreshEnabled: true,
            // 开发模式添加调试令牌（需在Firebase控制台配置）
            ...(process.env.NODE_ENV === 'development' && {
              debugToken: process.env.NEXT_PUBLIC_FIREBASE_APP_CHECK_DEBUG_TOKEN
            })
          });
        }
      }
    };

    initAppCheck();
  }, []);

  return null; // 该组件无需渲染UI
}

步骤3：在根布局中引入初始化组件

根布局为服务器组件，但可以安全引入客户端组件：

// app/layout.tsx
import FirebaseAppCheck from '@/components/FirebaseAppCheck';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="zh-CN">
      <body>
        <FirebaseAppCheck />
        {children}
      </body>
    </html>
  );
}

2. ReactFire适配方案 #

若坚持使用ReactFire，需确保所有ReactFire相关逻辑在客户端组件中执行：

// components/ReactFireAppCheckWrapper.tsx
'use client';

import { FirebaseAppProvider, useFirebaseApp } from 'reactfire';
import { initializeAppCheck, ReCaptchaV3Provider, isSupported } from 'firebase/app-check';
import { firebaseConfig } from '../firebase/config';
import { useEffect } from 'react';

export default function ReactFireAppCheckWrapper({ children }: { children: React.ReactNode }) {
  return (
    <FirebaseAppProvider firebaseConfig={firebaseConfig}>
      <AppCheckInitializer />
      {children}
    </FirebaseAppProvider>
  );
}

function AppCheckInitializer() {
  const app = useFirebaseApp();
  
  useEffect(() => {
    const init = async () => {
      if (typeof window !== 'undefined') {
        const supported = await isSupported();
        if (supported) {
          initializeAppCheck(app, {
            provider: new ReCaptchaV3Provider('你的ReCaptcha V3站点密钥'),
            isTokenAutoRefreshEnabled: true,
            ...(process.env.NODE_ENV === 'development' && {
              debugToken: process.env.NEXT_PUBLIC_FIREBASE_APP_CHECK_DEBUG_TOKEN
            })
          });
        }
      }
    };
    init();
  }, [app]);

  return null;
}

之后在根布局中替换为该组件即可。

开发模式关键配置 #

1. 调试令牌配置：开发时浏览器控制台会输出App Check调试令牌，复制该令牌到Firebase控制台的「App Check」→「应用」→「调试令牌」列表中，即可允许本地请求通过验证。
2. 授权域名：在Firebase控制台「Authentication」→「登录方法」→「授权域名」中添加localhost:3000。
3. 版本兼容：确保ReactFire版本与Firebase SDK版本匹配（如ReactFire v4.x对应Firebase v9.x）。

常见错误排查 #

• 若出现window is not defined：检查所有Firebase相关代码是否在'use client'组件中，避免在服务器组件中执行初始化逻辑。
• ReactFire持续报错：删除node_modules和package-lock.json后重新安装，确保依赖版本兼容。
• 开发模式验证失败：确认调试令牌已添加到Firebase控制台，且ReCaptcha密钥配置正确。

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