Nuxt3 SSR构建完全指南：从静态生成到真正服务端渲染的迁移实践-js教程-PHP中文网

Nuxt3 SSR构建完全指南：从静态生成到真正服务端渲染的迁移实践

本文详解如何将Nuxt应用从nuxt generate（SSG）正确切换为真正的服务端渲染（SSR），包括核心配置、构建命令差异、部署要求及常见HTML空白问题的根源与解决方案。

本文详解如何将nuxt应用从`nuxt generate`（ssg）正确切换为真正的服务端渲染（ssr），包括核心配置、构建命令差异、部署要求及常见html空白问题的根源与解决方案。

在Nuxt 3中，“构建为SSR”并非一个可选的构建产物，而是一种运行时渲染模式，它从根本上决定了应用如何响应HTTP请求——由Node.js服务器实时执行Vue组件并输出完整HTML。你当前遇到的问题（页面源码仅显示空

）正是典型SSG行为的体现：nuxt generate会预渲染所有路由为静态HTML文件，但不启用服务端数据获取和动态HTML合成能力，因此无法实现真正的SSR。

✅ 正确启用SSR的三步关键操作

显式开启SSR模式
在 nuxt.config.ts 中必须设置 ssr: true（Nuxt 3默认值即为true，但显式声明可避免歧义）：

// nuxt.config.ts
export default defineNuxtConfig({
  ssr: true, // ✅ 强制启用服务端渲染
  nitro: {
    preset: 'node-server', // 明确指定Node.js服务端预设（推荐）
  },
  // 其他配置...
})

使用正确的构建命令
nuxt generate → 仅用于SSG（静态站点）；
nuxt build → 才是生成SSR应用的正确命令：
```
# ✅ 构建SSR应用（生成可运行的Node.js服务器）
npm run build
# 或 pnpm build / yarn build

# ✅ 本地预览SSR效果（启动生产服务器）
npm run preview
```
执行后，构建产物位于 .output/server/ 目录，其中 index.mjs 即为Nitro引擎生成的Node.js入口文件。
部署需Node.js环境
SSR应用无法托管于纯静态托管平台（如Netlify、Vercel静态模式、FTP）。你必须部署到支持Node.js运行时的环境，例如：
- 自托管：PM2 + Nginx反向代理
- 云平台：Vercel Serverless Functions（选择Node.js运行时）、Cloudflare Workers（Nitro兼容）、Render、Railway
- 容器化：Docker + Node.js基础镜像

⚠️ 为什么你的导致HTML为空？

你代码中的逻辑：

const isPageReady = ref(false);
if (process.client) {
  isPageReady.value = true; // ❌ 仅客户端设为true
}

这会导致：

服务端渲染时：isPageReady 始终为 false → 被v-if移除 → 服务端输出空壳HTML（即你看到的
...
）；
客户端激活后：isPageReady 变为true → Vue才挂载真实内容 → 首屏出现明显“闪动”或白屏。

✅ 正确解法：移除该条件，依赖Nuxt SSR生命周期
Nuxt 3的useFetch、asyncData等钩子天然保障服务端数据就绪后再渲染。布局组件应无条件渲染，状态控制交由SSR友好的响应式逻辑：

<!-- layouts/default.vue -->
<template><v-app><!-- ✅ 移除 v-if="isPageReady" --><header></header><v-main><slot></slot></v-main><footer></footer></v-app></template>

若需控制加载状态，使用或$fetch().then(...)配合v-show（非v-if）实现渐进式展示，确保服务端仍渲染占位结构。

? 实战建议：验证SSR是否生效

检查页面源码（View Page Source）：
SSR成功时，应看到完整的、含语义化内容的HTML（如

Introduction
、文章段落文本），而非仅
。
禁用JavaScript后访问：
在浏览器开发者工具中禁用JS，刷新页面。SSR页面仍应显示可读内容；CSR/SSG则可能空白或仅显示骨架。
检查网络请求头：
SSR请求的User-Agent会被Nitro识别，且响应头中通常包含Server: Nitro。

? 总结：SSR不是“构建选项”，而是架构选择

维度	SSG (nuxt generate)	SSR (nuxt build)
构建产物	静态HTML/CSS/JS文件	Node.js服务器（.output/server/）
部署要求	任意静态托管（Netlify/Vercel）	Node.js运行时环境
首屏HTML	预渲染完成，完全静态	服务端实时生成，支持动态数据
适用场景	内容极少变动的文档站、博客	需实时数据、用户登录、SEO强依赖页面