Next.js+Firebase项目Vercel部署失败：auth/invalid-api-key错误

问题背景 #

开发的Next.js项目集成了Firebase Authentication和数据库，本地运行正常，但部署到托管平台（如Vercel）时构建失败，核心错误为Firebase: Error (auth/invalid-api-key)，尝试修改构建命令为CI= npm build后问题仍存在。

构建日志关键报错片段：

[02:58:21.879] unhandledRejection Error [FirebaseError]: Firebase: Error (auth/invalid-api-key).
[02:58:21.879]     at createErrorInternal (file:///vercel/path0/node_modules/@firebase/auth/dist/node-esm/totp-035c6eef.js:490:40)
...
[02:58:21.959] Error: Command "npm run build" exited with 1

核心原因 #

本地运行时.env文件中的Firebase配置能被正常读取，但部署构建阶段，托管平台未正确注入环境变量，或Firebase初始化逻辑在构建时（而非运行时）执行，导致API Key无效。CI= npm build仅关闭CI模式下的严格检查，无法解决环境变量或初始化时机问题。

解决方案 #

1. 正确配置托管平台的环境变量 #

• 登录托管平台的项目设置，找到环境变量配置项
• 添加与本地.env文件一致的Firebase配置变量，客户端使用的变量必须以NEXT_PUBLIC_为前缀，例如：

  NEXT_PUBLIC_FIREBASE_API_KEY=你的API密钥
  NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=你的Auth域名
  NEXT_PUBLIC_FIREBASE_PROJECT_ID=你的项目ID
  

• 保存后触发重新部署，确保新的环境变量被加载

2. 调整Firebase初始化时机 #

避免在SSR/SSG页面的顶层直接初始化Firebase Auth，防止构建阶段执行初始化逻辑：

• 将Firebase初始化封装为函数，仅在需要时调用：

  // firebase.js
  import { initializeApp } from "firebase/app";
  import { getAuth } from "firebase/auth";
  
  const firebaseConfig = {
    apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
    authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
    projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  };
  
  let app;
  let auth;
  
  export const getFirebaseApp = () => {
    if (!app) {
      app = initializeApp(firebaseConfig);
    }
    return app;
  };
  
  export const getFirebaseAuth = () => {
    if (!auth) {
      auth = getAuth(getFirebaseApp());
    }
    return auth;
  };
  

• 在客户端组件中，通过useEffect或事件触发时调用初始化：

  // 客户端组件
  import { getFirebaseAuth } from "../firebase";
  import { useEffect } from "react";
  
  export default function ClientComponent() {
    useEffect(() => {
      const auth = getFirebaseAuth();
      // 后续Auth操作
    }, []);
  
    return <div>客户端内容</div>;
  }
  

3. 区分SSR/SSG与客户端逻辑 #

• 若页面为SSG（静态生成），避免在页面组件中直接调用Firebase Auth相关方法，改为将需要Auth数据的部分拆分为客户端组件
• 若使用SSR（服务器端渲染），确保服务端能访问到非NEXT_PUBLIC_前缀的环境变量（无需前缀，直接在服务器端读取）

4. 验证环境变量可用性 #

在构建前添加验证步骤，确认环境变量已正确注入：

• 在package.json的build命令前添加验证脚本：

  "scripts": {
    "verify-env": "echo \"Checking Firebase API Key: $NEXT_PUBLIC_FIREBASE_API_KEY\"",
    "build": "npm run verify-env && next build"
  }
  

• 查看构建日志中的验证输出，确认API Key已正确加载

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