Nuxt3配置ssr:false构建后启动服务页面无显示如何解决

问题复现 #

项目nuxt.config.js配置如下：

import { defineNuxtConfig } from "nuxt";
import path from "path";
import fs from "fs";

export default defineNuxtConfig({
  builder: "webpack",
  ssr: false,

  hooks: {
    "build:done": (builder) => {
      const extraFilePath = path.join(
        builder.nuxt.options.buildDir + "/dist/server",
        "server.mjs"
      );
      fs.writeFileSync(extraFilePath, "export {};");
    },
  },
});

• 开发环境执行yarn dev启动正常
• 生产环境执行yarn build后，运行set HOST=127.0.0.1&&node ./.output/server/index.mjs启动服务，访问127.0.0.1:3000页面无内容
• ssr设为true时问题消失

核心诱因 #

• 自定义钩子逻辑有缺陷：你写的build:done钩子仅在构建临时目录（.nuxt）下生成空的server.mjs，这个操作原本是为了规避早期Nuxt3 webpack构建器在ssr:false下的文件引用报错，但完全没触及生产构建的最终产物目录.output。如果路径误写到Nitro服务端入口位置，直接用writeFileSync覆盖文件会把Nitro生成的「返回HTML壳、注入客户端静态资源、托管静态文件」的核心逻辑全部清空，服务端只能返回空响应。
• CSR模式构建适配缺失：ssr:false即纯客户端渲染模式下，服务端不需要做HTML渲染，只需要返回带客户端JS/CSS资源引用的基础HTML壳，webpack构建器在Nuxt3的部分版本中没有自动完成这部分资源注入逻辑，浏览器拿到空HTML后没有加载业务脚本，自然渲染不出内容。开启SSR时服务端会完整渲染HTML并自动注入hydration脚本，所以不会出现该问题。

解决方法 #

• 优先使用官方SPA构建命令：先删除自定义的build:done钩子逻辑，执行构建时带上spa参数，官方会自动处理CSR模式的产物适配，不需要手动生成空文件：

yarn build --spa

构建完成后正常启动.output/server/index.mjs即可。

• 必须保留自定义钩子时修正逻辑：如果有特殊依赖必须手动补充空导出，不要覆盖服务端入口文件，把钩子时机改为Nitro构建完成后，仅在需要的路径生成文件，不触碰核心服务逻辑，同时补充Nitro配置适配CSR模式：

import { defineNuxtConfig } from "nuxt";
import path from "path";
import fs from "fs";

export default defineNuxtConfig({
  builder: "webpack",
  ssr: false,
  nitro: {
    prerender: { crawlLinks: false }
  },
  hooks: {
    "nitro:compiled": (nitro) => {
      // 兼容旧构建逻辑生成需要的空server.mjs
      const extraPath = path.join(nitro.options.buildDir, "dist/server/server.mjs");
      fs.mkdirSync(path.dirname(extraPath), { recursive: true });
      fs.writeFileSync(extraPath, "export {};");
      // 禁止修改.output下的服务端入口文件，避免覆盖核心逻辑
    }
  }
});

• 无强依赖webpack时切换默认构建器：Vite作为Nuxt3官方默认构建器，对CSR模式的适配更完善，没有webpack构建器的这类边缘问题，移除配置中的builder: "webpack"即可默认启用Vite。

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