将Next.js应用部署至Firebase Hosting后网站无法显示的排查与正确部署方法

Great question—this is a super common pitfall when deploying Next.js to Firebase Hosting, since the .next folder isn't meant to be served directly as a static public directory. Let's break down why this happens and walk through the correct deployment steps.

Common Causes for the Broken Site #

Even though the firebase deploy command succeeds, your app fails to load for these key reasons:

• .next isn't a static public directory: The .next folder is Next.js's build output for its own server runtime (used with next start). It contains compiled server-side code, chunked assets, and metadata—not the flat, static HTML/CSS/JS structure Firebase Hosting expects for direct static hosting. Firebase can't resolve the server-side logic in .next, so it can't serve your app's pages correctly.
• Missing root entry point: Firebase Hosting looks for an index.html file at the root of your specified public directory. The .next folder doesn't have this at the root; any statically generated pages would be nested in subfolders like .next/server/pages, which Firebase doesn't know to serve by default.
• Asset path mismatches: Resources like CSS, JS, and images in .next have internal paths that assume they're being served by the Next.js server. When Firebase hosts these files directly, the paths break, leading to missing assets and blank pages.

Correct Deployment Methods #

There are two main approaches depending on whether your Next.js app is fully static (no SSR/ISR/API routes) or requires server-side functionality.

1. For Fully Static Next.js Apps (SSG Only) #

If your app uses only Static Site Generation (no server-side rendering, incremental static regeneration, or API routes), you can export it as pure static files:

1. Configure Next.js for static export:
   In your next.config.js, add the output option (for Next.js 12.2+):

   /** @type {import('next').NextConfig} */
   const nextConfig = {
     output: 'export',
     // other config options...
   }
   module.exports = nextConfig
   

2. Build the static output:
   Run the build command—this will generate an out folder with all static assets:

   npm run build
   

3. Update Firebase config:
   In firebase.json, set the public directory to out:

   {
     "hosting": {
       "public": "out",
       "ignore": [
         "firebase.json",
         "**/.*",
         "**/node_modules/**"
       ],
       "cleanUrls": true,
       "trailingSlash": true
     }
   }
   

4. Deploy:
   Run the standard deploy command:

   firebase deploy
   

2. For Apps with SSR/ISR/API Routes #

If your app uses Server-Side Rendering, Incremental Static Regeneration, or API routes, you need to use Firebase Functions to run the Next.js server alongside Firebase Hosting:

1. Install dependencies:
   Install Firebase Functions and Admin SDK:

   npm install firebase-functions firebase-admin next --save
   

2. Set up the Firebase Function:
   Create a functions folder in your project root, then add an index.js file with this code:

   const { https } = require('firebase-functions');
   const next = require('next');
   
   const dev = process.env.NODE_ENV !== 'production';
   const app = next({ dev, conf: { distDir: '.next' } });
   const handle = app.getRequestHandler();
   
   // Export the Next.js app as a Firebase Function
   exports.nextApp = https.onRequest((req, res) => {
     // Log requests for debugging (optional)
     console.log(`Request for ${req.originalUrl}`);
     return app.prepare().then(() => handle(req, res));
   });
   

3. Update Firebase config:
   Modify firebase.json to route all requests to your function, while hosting static assets from .next/static:

   {
     "hosting": {
       "public": ".next/static",
       "ignore": [
         "firebase.json",
         "**/.*",
         "**/node_modules/**"
       ],
       "rewrites": [
         {
           "source": "**",
           "function": "nextApp"
         }
       ]
     }
   }
   

4. Deploy Functions and Hosting:
   Deploy both the function and hosting assets:

   firebase deploy --only functions,hosting
   

Quick Troubleshooting Tips #

• If you see a 404 after deploying, double-check your firebase.json public directory setting and make sure the correct folder (out or .next/static) exists.
• For SSR deployments, ensure your Firebase Function has enough memory allocated (default is 256MB; you can increase this in the Firebase Console under Functions > Your Function > Runtime, build, and connections settings).
• Clear your browser cache or use incognito mode after deploying—old cached assets can cause unexpected behavior.

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