NextJS+NX项目中Firebase Admin的SSR初始化时机问题

问题背景 #

基于NextJS与NX的项目使用Firestore作为后端，已配置API路由及initFirebaseAdmin工具库。CSR组件运行正常，但SSR组件中initFirebaseAdmin未被调用，导致Firestore提示未初始化。需求是让业务库无需关注环境变量与Firebase配置，实现服务器端代码运行时自动执行初始化。

解决方案 #

方法1：通过Next.js Middleware全局初始化 #

Middleware会在所有服务器端请求（包括SSR页面、API路由）之前执行，适合做全局初始化。

1. 在项目根目录创建middleware.ts文件
2. 导入并执行初始化逻辑，配置匹配所有需要服务器端处理的路由：

// middleware.ts
import { initFirebaseAdmin } from './path/to/initFirebaseAdmin';
import * as admin from 'firebase-admin';

// 自动执行Firebase Admin初始化
initFirebaseAdmin({
  credential: admin.credential.cert({
    projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID!,
    clientEmail: process.env.NEXT_FIREBASE_ADMIN_PRIVATE_CLIENT_EMAIL!,
    privateKey: process.env.NEXT_FIREBASE_ADMIN_PRIVATE_KEY!.replace(/\\n/g, '\n'),
  }),
});

export function middleware() {
  // 无需额外逻辑，初始化已在文件导入阶段执行
}

// 配置匹配所有服务器端路由，可根据业务调整
export const config = {
  matcher: [
    '/api/:path*',
    '/:path*' // 覆盖所有SSR页面路由
  ],
};

方法2：封装Firestore工具函数，自动触发初始化 #

将Firebase初始化与Firestore实例获取封装在一起，业务代码调用工具函数时自动完成初始化，无需关心配置细节。

优化initFirebaseAdmin工具库

// initFirebaseAdmin.ts
import * as admin from 'firebase-admin';
import * as Sentry from '@sentry/nextjs';

// 自动读取环境变量完成初始化，无需外部传入配置
export const initFirebaseAdmin = (): boolean => {
  try {
    // 避免重复初始化
    if (admin.apps.length > 0) return true;

    const adminConfig = {
      credential: admin.credential.cert({
        projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID!,
        clientEmail: process.env.NEXT_FIREBASE_ADMIN_PRIVATE_CLIENT_EMAIL!,
        privateKey: process.env.NEXT_FIREBASE_ADMIN_PRIVATE_KEY!.replace(/\\n/g, '\n'),
      }),
    };

    admin.initializeApp(adminConfig);
    return true;
  } catch (e) {
    Sentry.captureException(e);
    return false;
  }
};

// 导出自动初始化的Firestore实例
export const getFirestore = () => {
  initFirebaseAdmin();
  return admin.firestore();
};

修改业务操作代码

直接使用封装好的getFirestore，无需手动调用初始化：

// lib/user/operation.ts
import { getFirestore } from '../initFirebaseAdmin';

export async function placesGet(params) {
    const firestore = getFirestore();
    let query = firestore.collection('users');
    // 后续业务逻辑...
}

方法3：利用NX项目钩子提前初始化 #

在NX monorepo中，可通过配置项目启动依赖，让Firebase初始化在NextJS服务启动前执行。

修改项目的project.json：

{
  "targets": {
    "serve": {
      "executor": "@nx/next:server",
      "options": {
        "buildTarget": "your-project:build",
        "dev": true
      },
      "configurations": {
        "production": {
          "buildTarget": "your-project:build:production"
        }
      },
      "dependsOn": ["init-firebase"]
    },
    "init-firebase": {
      "executor": "@nx/js:node",
      "options": {
        "script": "apps/your-project/src/initFirebaseAdmin.ts"
      }
    }
  }
}

启动项目时，NX会先执行init-firebase脚本完成初始化，后续所有服务器端代码均可直接使用已初始化的Firebase实例。

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