Next.js TypeScript集成Firebase AppCheck遇ReferenceError: self未定义

问题场景 #

使用 Next.js 14.1.4 + TypeScript 集成 Firebase AppCheck 时，为启用调试模式在firebase.ts中添加代码：

const fbapp = initializeApp(firebaseConfig);

if (process.env.NODE_ENV === "development") {
  // @ts-ignore
  self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
}

initializeAppCheck(fbapp, {
  provider: new ReCaptchaV3Provider(
    process.env.NEXT_PUBLIC_GOOGLE_RECAPCHA_PUBLIC_KEY as string
  ),
  isTokenAutoRefreshEnabled: true
})

Firebase 可识别调试令牌配置并输出令牌，但运行npm run dev:next时触发ReferenceError: self is not defined错误，报错指向设置调试令牌的代码行，且错误发生在服务端渲染(SSR)阶段。

报错日志 #

jackr@Jacks-PC MINGW64 /d/dev/NoPlus-web/noplus-web (web-dev)
$ npm run dev:next

> noplus-web@0.1.0 dev:next
> next dev

   ▲ Next.js 14.1.4
   - Local:        http://localhost:3000
   - Environments: .env

 ✓ Ready in 7.9s
 ○ Compiling / ...
 ⨯ Failed to find font override values for font `Bungee Spice`
 ⨯ Failed to find font override values for font `Bungee Spice`
 ✓ Compiled / in 22.2s (4020 modules)
 ⨯ src\components\firebase.ts (22:2) @ self
 ⨯ ReferenceError: self is not defined
    at eval (./src/components/firebase.ts:27:5)
    at (ssr)/./src/components/firebase.ts (D:\dev\NoPlus-web\noplus-web\.next\server\app\page.js:557:1)
    at __webpack_require__ (D:\dev\NoPlus-web\noplus-web\.next\server\webpack-runtime.js:33:43)
    at eval (./src/components/presets/functions/welcomeUser.tsx:6:67)
    at (ssr)/./src/components/presets/functions/welcomeUser.tsx (D:\dev\NoPlus-web\noplus-web\.next\server\app\page.js:667:1)
    at __webpack_require__ (D:\dev\NoPlus-web\noplus-web\.next\server\webpack-runtime.js:33:43)
    at eval (./src/app/page.tsx:12:84)
    at (ssr)/./src/app/page.tsx (D:\dev\NoPlus-web\noplus-web\.next\server\app\page.js:440:1)
    at __webpack_require__ (D:\dev\NoPlus-web\noplus-web\.next\server\webpack-runtime.js:33:43)
    at JSON.parse (<anonymous>)
  20 | if (process.env.NODE_ENV === "development") {
  21 |   // @ts-ignore
> 22 |   self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
     |  ^
  23 | }
  24 |
  25 | initializeAppCheck(fbapp, {
 ✓ Compiled in 2.5s (1850 modules)
 ✓ Compiled in 552ms (1836 modules)

解决方案 #

原因分析 #

self是浏览器环境的全局变量，服务端渲染过程中不存在该对象，因此在SSR阶段执行这段代码会触发错误。

修复方案1：判断浏览器环境后执行 #

修改firebase.ts中的调试令牌设置逻辑，先检查当前是否处于浏览器环境：

const fbapp = initializeApp(firebaseConfig);

if (process.env.NODE_ENV === "development") {
  // 仅在浏览器环境下设置调试令牌
  if (typeof window !== 'undefined') {
    // @ts-ignore
    window.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
  }
}

initializeAppCheck(fbapp, {
  provider: new ReCaptchaV3Provider(
    process.env.NEXT_PUBLIC_GOOGLE_RECAPCHA_PUBLIC_KEY as string
  ),
  isTokenAutoRefreshEnabled: true
})

修复方案2：将Firebase AppCheck初始化放在客户端组件 #

在firebase.ts顶部添加'use client'指令，确保整个初始化逻辑仅在客户端执行：

'use client';

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

const firebaseConfig = { /* 你的Firebase配置 */ };

const fbapp = initializeApp(firebaseConfig);

if (process.env.NODE_ENV === "development") {
  // @ts-ignore
  window.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
}

initializeAppCheck(fbapp, {
  provider: new ReCaptchaV3Provider(
    process.env.NEXT_PUBLIC_GOOGLE_RECAPCHA_PUBLIC_KEY as string
  ),
  isTokenAutoRefreshEnabled: true
})

内容的提问来源于stack exchange，提问作者DJL - Jack