Next.js应用中Firestore已运行仍反复设置模拟器的报错问题

报错原因 #

Next.js开发环境的热重载机制会重复加载Firebase配置模块，导致每次热重载都会重新执行服务初始化、模拟器连接的逻辑。而Firestore等Firebase服务的实例一旦创建完成，就不允许再修改配置参数，因此触发该报错。

解决方案 #

核心逻辑是增加实例缓存判断，确保Firebase App初始化、模拟器连接逻辑全局仅执行一次，修改后的初始化代码如下：

import { initializeApp, getApp, getApps } from "firebase/app";
import { getAuth, connectAuthEmulator } from "firebase/auth";
import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";
import { getStorage, connectStorageEmulator } from "firebase/storage";
import { getFunctions, connectFunctionsEmulator } from "firebase/functions";

// 替换为你自己的Firebase配置
const firebaseConfig = {};

// 优先复用已初始化的Firebase实例，避免重复初始化
const firebaseApp = getApps().length ? getApp() : initializeApp(firebaseConfig);

const mode = "emulate";

const auth = getAuth(firebaseApp);
const db = getFirestore(firebaseApp);
const storage = getStorage(firebaseApp);
const functions = getFunctions(firebaseApp);

if (mode === "emulate" && process.env.NODE_ENV === "development") {
  // 全局标记避免重复连接模拟器
  if (!global._firebaseEmulatorsConnected) {
    connectAuthEmulator(auth, "http://localhost:9099");
    connectFirestoreEmulator(db, "localhost", 8080);
    connectStorageEmulator(storage, "localhost", 9199);
    connectFunctionsEmulator(functions, "localhost", 5001);
    global._firebaseEmulatorsConnected = true;
  }
}

export { firebaseApp, db, auth, storage, functions };

注意事项 #

• 新增的process.env.NODE_ENV === "development"判断可以避免生产环境意外连接本地模拟器
• 若使用TypeScript开发，需要在全局类型声明文件中添加declare var _firebaseEmulatorsConnected: boolean;避免类型报错
• 该初始化代码需单独存为公共工具模块，不要放在页面、组件内部执行

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