Next.js添加SSR后部署至Firebase页面空白问题求助

问题根源 #

Next.js静态页面可直接在Firebase Hosting运行，但SSR依赖服务器端代码执行，必须通过Cloud Functions转发请求。空白页基本是因为请求未正确路由到SSR函数，或者函数执行出错导致无响应。

先查配置文件 #

1. package.json #

确保未使用静态导出命令，且依赖版本兼容：

{
  "scripts": {
    "dev": "next dev",
    "build": "next build", // 仅保留该命令，删除next export
    "start": "next start"
  },
  "dependencies": {
    "next": "^13.x",
    "react": "^18.x",
    "react-dom": "^18.x"
  }
}

踩坑点：如果build脚本混有next export，会强制将SSR页面转成静态文件，直接丢失SSR能力，必须移除。

2. firebase.json #

核心是配置Hosting重写规则，将所有请求转发到Cloud Functions，同时指定正确的静态资源目录：

{
  "hosting": {
    "public": ".next/static", // 仅托管静态资源，页面逻辑交给云函数处理
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "function": "nextSSR" // 此处函数名需与云函数导出名完全一致
      }
    ]
  },
  "functions": {
    "source": ".", // 或你的云函数源码目录，比如"functions"
    "runtime": "nodejs18" // 必须使用支持Next.js的Node版本，避免过低版本
  }
}

常见错误：

• 未配置rewrites规则：Hosting直接返回静态资源，无法找到SSR页面
• runtime版本过低：如nodejs16，与新版Next.js不兼容
• public目录设为"out"：这是静态导出目录，SSR项目无需配置

3. .firebaserc #

确认部署目标为正确的Firebase项目：

{
  "projects": {
    "default": "your-real-project-id"
  }
}

检查云函数代码 #

云函数需正确初始化Next.js并处理请求，示例代码（如functions/index.js）：

const { https } = require('firebase-functions');
const next = require('next');

const isDev = process.env.NODE_ENV !== 'production';
const nextApp = next({ dev: isDev, conf: { distDir: '.next' } });
const requestHandler = nextApp.getRequestHandler();

exports.nextSSR = https.onRequest((req, res) => {
  // 必须等待Next.js准备完成后再处理请求
  return nextApp.prepare().then(() => requestHandler(req, res));
});

踩坑点：

• 未返回nextApp.prepare()的Promise：函数提前结束，返回空响应
• distDir配置错误：找不到构建后的.next目录，导致渲染失败
• 函数导出名与firebase.json中不一致：请求无法转发到云函数

部署日志排查 #

执行firebase deploy --only functions hosting后，重点关注：

• 云函数是否部署成功，是否存在依赖安装失败、语法错误
• Hosting的重写规则是否被正确应用
• 函数的入口路径是否正确

若部署后函数报错，可前往Firebase控制台→Functions→日志查看具体错误信息，比如依赖缺失、代码逻辑bug。

浏览器端排查 #

控制台错误 #

• 500错误：云函数执行失败，需查看函数日志定位原因
• 404错误：重写规则未生效，请求未到达云函数
• 白屏无报错：可能是SSR页面渲染时抛出静默错误，需在代码中添加日志调试

网络请求 #

查看主页面请求状态：

• 200但内容为空：云函数返回空响应，大概率是Next.js渲染失败
• 404：Hosting未将请求转发给云函数，检查rewrites规则

修复步骤速览 #

1. 删除package.json中的next export命令，确保build仅执行next build
2. 修正firebase.json的rewrites规则，将所有请求转发到正确的云函数
3. 云函数使用nodejs18+的runtime，与本地Node版本保持一致
4. 检查云函数代码，确保正确初始化Next.js并返回准备完成的Promise
5. 本地先执行next build && next start，确认SSR页面正常后再部署
6. 部署后查看云函数日志，排查执行错误

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