如何避免因API路由需环境变量导致Next.js重复构建？

为什么构建时会触发SDK读变量 #

Next.js执行next build时，会扫描所有API路由文件并加载对应的模块，模块顶层的代码（不在函数内部的代码）会被直接执行。如果你的Firebase Admin初始化代码写在API路由的顶层（比如直接调用admin.initializeApp()），构建过程中Node.js加载这个模块时就会执行这段初始化代码，SDK自然会去读环境变量，变量不存在就会导致构建失败。

举个典型的错误写法：

// pages/api/user.js
import admin from 'firebase-admin';

// 这段顶层代码会在构建时执行
admin.initializeApp({
  credential: admin.credential.cert({
    projectId: process.env.FIREBASE_PROJECT_ID,
    clientEmail: process.env.FIREBASE_CLIENT_EMAIL,
    privateKey: process.env.FIREBASE_PRIVATE_KEY,
  })
});

export default function handler(req, res) {
  // 请求处理逻辑
}

怎么避免构建时触发 #

核心思路就是把初始化逻辑延迟到API被实际请求时再执行，有两种常用方式：

方式1：单例模式，在请求处理函数内初始化 #

把初始化逻辑封装成单例函数，只有在处理请求时才调用，确保构建阶段不会执行：

// pages/api/user.js
import admin from 'firebase-admin';

let adminInstance;

function getAdmin() {
  if (!adminInstance) {
    adminInstance = admin.initializeApp({
      credential: admin.credential.cert({
        projectId: process.env.FIREBASE_PROJECT_ID,
        clientEmail: process.env.FIREBASE_CLIENT_EMAIL,
        privateKey: process.env.FIREBASE_PRIVATE_KEY.replace(/\\n/g, '\n'),
      })
    });
  }
  return adminInstance;
}

export default function handler(req, res) {
  const admin = getAdmin();
  // 用admin处理请求
}

方式2：抽离初始化模块，动态导入 #

把初始化代码放到单独文件，在API路由里用动态导入，构建时不会解析这段导入的代码，只有请求时才加载执行：

// lib/firebase-admin.js
import admin from 'firebase-admin';

export default function initAdmin() {
  return admin.initializeApp({
    credential: admin.credential.cert({
      projectId: process.env.FIREBASE_PROJECT_ID,
      clientEmail: process.env.FIREBASE_CLIENT_EMAIL,
      privateKey: process.env.FIREBASE_PRIVATE_KEY.replace(/\\n/g, '\n'),
    })
  });
}

// pages/api/user.js
export default async function handler(req, res) {
  const { default: initAdmin } = await import('../lib/firebase-admin');
  const admin = initAdmin();
  // 处理请求
}

核心总结 #

• API路由没有getServerSideProps这类控制构建行为的机制，构建时会执行模块所有顶层代码
• 只要把Firebase Admin的初始化逻辑放到函数内部，延迟到请求阶段执行，就能避免构建时读取环境变量

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