NextJS构建时无法连接Firebase Firestore的问题排查

问题背景 #

开发NextJS集成Firebase的项目时，开发模式下所有功能正常，但执行npm run build命令构建项目时，触发如下错误：

@firebase/firestore: Firestore (X.X.X): Could not reach Cloud Firestore backend. Backend didn't respond within 10 seconds.

This typically indicates that your device does not have a healthy Internet connection at the moment. The client will operate in offline mode until it is able to successfully connect to the backend.
    
Error occurred prerendering page "/". Read more: https://nextjs.org/docs/messages/prerender-error. FirebaseError: Failed to get document because the client is offline.

项目核心代码片段：

import { initializeApp } from "firebase/app";
import { getFirestore, collection, getDocs} from 'firebase/firestore';
import React from 'react';
import Component from '../component/Component ';

export default function Home({ToReturn}) {
   return(
       <div className="App">
         <Component />
       </div>
   )
}

export async function getStaticProps(){
    const firebaseConfig = {Keys : "Firebase Keys etC..."};
    const app = initializeApp(firebaseConfig, {
        experimentalForceLongPolling: true,
        useFetchStreams: false,
    });
    const db = getFirestore(app);

    const ToReturn = { CharacterData : {} }
    
    const CharacterList = await getDocs(collection(db, 'Characters'));

    CharacterList.docs.map((Character) =>{      
      return ToReturn["CharacterData"][Character.id] = Character.data();
    });
  
  return {
    props : {
      ToReturn
    },
    revalidate: 100,
  };
};

已尝试的无效操作：添加experimentalForceLongPolling: true参数、新建仅集成单个Firebase集合的测试项目、修改Next Export配置；仅使用Firestore REST API时可正常完成构建。

错误原因 #

1. 客户端SDK的环境适配问题：当前使用的Firebase客户端SDK是为浏览器环境设计的，在NextJS构建阶段的Node.js服务端环境中，会默认尝试使用WebSocket等浏览器专属通信机制，而Node.js环境不支持这些特性，导致连接超时并触发离线模式。
2. 重复初始化Firebase实例：每次执行getStaticProps时都重新初始化Firebase App，可能引发实例冲突，进一步干扰连接流程。
3. 缺少服务端专属配置：客户端SDK在服务端环境需要额外配置来适配Node.js的网络请求逻辑，仅靠experimentalForceLongPolling无法完全弥补环境差异带来的问题。

可行解决方案 #

• 切换到Firebase Admin SDK：在NextJS的服务端逻辑（如getStaticProps、getServerSideProps）中使用Firebase Admin SDK，它是专门为Node.js服务端环境开发的，能稳定在构建阶段连接Firestore。
• 全局初始化Firebase实例：将Firebase App的初始化逻辑抽离到单独模块中，通过单例模式确保整个应用只存在一个Firebase实例，避免重复初始化的冲突。
• 适配客户端SDK的服务端配置：若坚持使用客户端SDK，需在服务端环境中显式配置Firestore使用Node.js的HTTP请求适配器，但这种方式的稳定性不如Admin SDK。

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