在已初始化的Firebase项目中创建NextJS应用并替换现有静态站点

1. 前置检查与准备 #

• 确认本地Next.js项目已调试完毕，所有功能符合上线要求
• 进入已初始化的Firebase项目根目录，确认firebase.json、.firebaserc配置文件和原有Functions代码完好
• 升级Firebase CLI到最新版本：npm install -g firebase-tools，执行firebase login确保登录的账号拥有对应项目的操作权限

2. 修改Firebase配置适配Next.js #

场景1：使用Next.js SSR/ISR等服务端能力 #

• 在Firebase项目根目录安装基础依赖：npm install next react react-dom firebase-functions firebase-admin
• 编辑firebase.json，保留原有Functions配置不变，仅修改托管部分配置，示例如下：

{
  "functions": {
    "source": "functions",
    "runtime": "nodejs18" // 保持你原有配置的运行时版本即可
  },
  "hosting": {
    "source": ".",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ]
  }
}

如果你的Next.js项目存放在Firebase根目录的子文件夹内，将hosting.source的取值改为对应子文件夹的相对路径即可，比如"./next-project"

场景2：使用Next.js静态导出模式 #

如果你的Next.js项目开启了静态导出（next.config.js中配置了output: 'export'），无需改动Functions相关配置，仅需要将hosting.public字段指向Next.js构建后生成的out目录即可：

{
  "functions": {
    // 完全保留原有Functions配置即可
  },
  "hosting": {
    "public": "./out",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ]
  }
}

3. 本地验证兼容性 #

• 执行firebase emulators:start启动本地模拟器，访问默认托管地址（通常为http://localhost:5000）确认Next.js站点运行正常，同时验证原有业务Functions的调用逻辑不受影响

4. 部署上线 #

• 本地测试无异常后执行部署命令：
  • 若使用SSR/ISR模式：firebase deploy --only hosting,functions，该命令仅更新托管内容和Next.js关联的服务端函数，不会覆盖你已部署的其他业务Functions
  • 若使用静态导出模式：先执行next build生成out目录，再运行firebase deploy --only hosting即可
• 部署完成后访问你的Firebase托管域名，确认站点已替换为Next.js版本、所有功能正常运行即可

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