Nuxt 3渲染模式控制：SSR/CSR/SSG与routeRules实战详解

在 Nuxt 项目里折腾久了你会发现，很多奇奇怪怪的问题——首屏白屏时间太长、SEO 死活不收录、接口偶尔报错、页面在某些环境下加载行为不一致——十有八九都跟渲染模式有关。市面上的教程大多只会告诉你“Nuxt 默认是 SSR，想改 CSR 就把 ssr 设成 false”，但实际项目里根本没那么简单：有的页面需要服务端渲染保 SEO，有的页面是登录后的后台操作台、完全不需要 SEO 还想省服务器压力，甚至同一个项目的不同路由要采取完全不同的策略。这时候你就会发现，真正需要搞懂的是“怎么控制 Nuxt 页面的渲染模式”，而不是只会开一个全局开关。

这篇内容我会从 Nuxt 3 的渲染模式底层逻辑讲起，把客户端渲染和服务端渲染的差异、各自的适用场景、怎么在全局和单页面级别做精细控制，以及我实际踩过的坑全部过一遍。适合刚上手 Nuxt 想搞清楚 SSR/CSR 区别的初学者，也适合已经在用 Nuxt 但想优化页面性能、排查接口和部署问题的开发者。

1. 先搞明白：Nuxt 为什么有渲染模式这回事

1.1 从一张页面被打开说起：CSR / SSR / SSG 的本质区别

要理解 Nuxt 的渲染模式，先得知道一个完整的页面到底是怎么出现在用户浏览器里的。传统服务端渲染的流程是：浏览器输入网址，服务器收到请求后把数据查好、把 HTML 拼好，直接返回一段已经含有内容的完整 HTML。浏览器拿到手就能直接显示，这个过程就是 SSR（Server-Side Rendering）。

而纯客户端渲染 CSR（Client-Side Rendering）则是：服务器只返回一个几乎空的 HTML 外壳和一堆 JavaScript 文件，浏览器下载完 JS 后，由 JavaScript 在本地动态创建 DOM、调用接口、填充内容。整个过程在浏览器里完成，所以叫客户端渲染。

还有一个容易被混淆的 SSG（Static Site Generation），它在构建时就把页面生成好，变成静态 HTML 文件存在磁盘上，部署时服务器只负责把文件发出去，不需要每次请求都重新渲染。Nuxt 3 里这三者全部支持，而且可以在一个项目里同时存在。

很多人以为“服务端渲染 = 性能更好”，这其实是个误区。SSR 的优势是 SEO 友好、首屏内容到达速度快（因为 HTML 里有内容），但代价是服务器每次请求都要跑一遍渲染逻辑，高并发下 CPU 和内存压力很大。CSR 恰好相反，首屏要靠 JS 跑完才能看到内容，但一旦静态资源上了 CDN，服务器压力就非常小。SSG 则适合内容基本不变、更新不频繁的站点。

1.2 Nuxt 3 的默认哲学：全都要，但要有选择

Nuxt 2 时代渲染模式非常简单：要么全部 SSR，要么全部 CSR。到了 Nuxt 3，Vue 生态全面拥抱 Vite，渲染模式的控制变得灵活了很多。它默认启用了服务端渲染，但同时允许你通过配置让某些页面走纯客户端渲染，甚至支持在运行时通过路由规则去决定某个 URL 用哪种方式响应。

Nuxt 3 这个设计的核心思路是：不强迫你在“全局 SSR”和“全局 CSR”之间二选一，而是让你根据业务场景去精细化控制。典型例子是电商站：商品详情页需要 SEO，必须服务端渲染；用户购物车和结算页是登录后操作，不需要搜索引擎收录，为了降低服务器压力可以改成客户端渲染；而像 /about 这种基本不变化的页面，直接用 SSG 静态生成是最优解。

但灵活也意味着复杂度。你需要在动手前想清楚每个页面的诉求，而不是把 routeRules 里的配置乱写一通。后面我会针对实际使用场景，把每一步怎么配置、为什么这么做讲清楚。

1.3 影响范围：不只是 SEO 和性能

渲染模式的选择会牵一发动全身，它影响的远不止“搜索引擎能不能收录”这一个维度。首先是接口调用：SSR 模式下，页面组件里的数据请求是在服务端发起的，请求的目标地址、鉴权方式都跟浏览器环境不一样；CSR 模式下所有请求都在浏览器发起，CORS、Cookie、登录态的处理就变成了前端的事。

其次是部署架构：纯 SSR 应用必须跑在 Node.js 服务上，无法直接扔到纯静态托管平台；SSG 应用则可以扔到 Nginx 或者对象存储上。第三是开发调试体验：SSR 模式下，浏览器里看到的 DOM 和组件代码里的 DOM 可能不一致，排查样式和交互问题时要多留意服务端渲染和客户端渲染的差异。

还有一个经常被忽略的点是安全。服务端渲染时，你的接口密钥、数据库连接信息如果不能在服务端代码里被妥善处理，很容易被暴露到客户端 bundle 里。渲染模式的切换不是改个布尔值那么简单，你得重新审视整个数据链路。

2. 全局控制渲染模式：nuxt.config.ts 里的 ssr 开关

2.1 设置全局 SSR 模式：ssr: true

如果你不做任何设置，Nuxt 3 默认就是开启服务端渲染的。通常不需要在配置文件里显式写 ssr: true，但如果你想让人一眼看出项目的模式，可以在 nuxt.config.ts 里写上：

typescript复制export default defineNuxtConfig({
  ssr: true,
  // 其他配置...
})

在这个模式下，应用启动后会启动一个 Node.js 服务，每次请求到达时，Nuxt 会在服务端执行 Vue 组件的 setup 逻辑、数据获取逻辑，渲染出完整的 HTML 字符串返回给浏览器。浏览器拿到后，会把这个 HTML 直接显示出来，然后再加载 JS 做“水合”（hydration），让页面变成可交互的 Vue 应用。

全局 SSR 模式适合的内容类型很明确：内容型网站、官网、博客、电商详情页、需要被分享到社交平台并展示预览卡片的应用。这种模式的关键收益是任何爬虫拿到的 HTML 都是完整内容，不需要执行 JavaScript 就能读取。

这里要提醒一句：SSR 不是免费的午餐。服务端执行组件代码意味着你的代码必须能在 Node.js 环境运行。比如你在组件里直接用了 window、document、localStorage，SSR 阶段就会直接报错，因为 Node.js 里根本没有这些对象。这类问题很常见，后面排查章节我会专门讲。

2.2 设置全局 CSR 模式：ssr: false

把 ssr 设置成 false，就变成了典型的单页应用（SPA）模式：

typescript复制export default defineNuxtConfig({
  ssr: false,
  // 其他配置...
})

这个模式下的 Nuxt 本质上就是一个 Vue SPA，服务器只返回一个初始 HTML 外壳，所有的页面渲染、路由切换都在浏览器端完成。它的好处是部署简单，构建产物是纯静态文件，任何能托管静态文件的平台都能跑，服务器没有任何渲染压力。对后台管理系统、工具类应用、内部平台这类不需要 SEO 的场景非常合适。

但 ssr: false 也有两个显著的坑。第一个是首屏加载速度和白屏时间：页面初始 HTML 里没有内容，要等 JS bundle 下载、执行完以后才能渲染出实际内容。项目越大、依赖越多，白屏时间就越长，尤其是在弱网环境下体验很糟糕。第二个是搜索引擎收录：虽然 Google 可以执行 JS 渲染页面，但它对 SPA 的收录和排名效果始终不如直接返回内容的 SSR 页面稳定。如果你的项目同时需要后台和面向搜索引擎的页面，就不建议全局关掉 SSR。

2.3 全局模式的适用场景与配置对比

我用自己的经验给这两个模式做了个简单对比，方便你快速判断自己该用哪个。

需要注意，上面的“首屏速度”不是绝对的。如果你的 CSR 应用把静态资源全部上了 CDN，首屏加载速度也可能比未优化 SSR 要快。但考虑到 SEO 和社交分享预览，SSR 仍然有不可替代的优势。

2.4 修改全局模式之后，需要检查的配套配置

把 ssr 开关切来切去不是改一行配置就完事，有几个配套项需要同步检查和调整。

第一个是 Nitro 部署目标。ssr: true 时，构建产物默认是 Node 服务，你需要部署到支持 Node.js 的服务器；如果你只是想输出静态文件，需要配置 nitro: { preset: 'static' } 或者用 nuxi generate 命令生成。ssr: false 时构建出的就是纯静态资源，需要确认 baseURL 配置是否正确，否则部署到子路径下会找不到资源。

第二个是接口代理配置。SSR 模式下，服务端请求接口不存在跨域问题；但一旦切到 CSR，浏览器直接请求接口就会遇到 CORS。建议在 Nuxt 里配置 runtimeConfig 或者 Nitro 的 devProxy，把接口请求转发到后端服务，避免开发和部署时被跨域卡住。

第三个是环境变量。服务端代码里能访问的环境变量不同于客户端，Nuxt 要求使用 NUXT_ 前缀且通过 runtimeConfig 暴露给客户端。切模式后要检查环境变量是否在对应环境里可见，否则很容易出现“本地好好的，部署后接口就 401/404”的尴尬情况。

3. 按页面级别精细控制：routeRules 精准掌控渲染方式

3.1 routeRules 解决了什么问题

全局开关只能管一整个项目，但实际业务里一个项目往往包含了多种类型页面，这时候全局开关就不够用了。Nuxt 3 提供了一个重要的配置项 routeRules（路由规则），它可以针对不同的 URL 路径设置不同的渲染模式和缓存策略，这是 Nuxt 3 比 Nuxt 2 好用很多的原因之一。

routeRules 支持的能力包括：ssr（是否服务端渲染）、swr（静态资源再验证，类似于增量静态再生成）、static（静态生成）、redirect（重定向）、proxy（代理）等。它可以精确匹配某个路径，也可以使用通配符匹配一组路径。这样一来，一个项目就能同时存在 SSR 页面、CSR 页面、静态页面，互不干扰。

3.2 配置示例：不同页面用不同渲染模式

假设你现在要做一个电商项目，有四个典型页面：首页（需要 SEO）、商品列表页（需要 SEO 和实时库存）、购物车页（用户专属，不需要 SEO）、结算页（用户专属且交互复杂）、以及一个活动落地页（内容基本不变）。用 routeRules 可以这样配置：

typescript复制export default defineNuxtConfig({
  routeRules: {
    '/': { ssr: true },                          // 首页走服务端渲染
    '/products/**': { ssr: true, swr: 60 },      // 商品列表走 SSR + SWR 缓存 60 秒
    '/cart/**': { ssr: false },                  // 购物车走客户端渲染
    '/checkout/**': { ssr: false },              // 结算页走客户端渲染
    '/campaign/**': { static: true },            // 活动页构建时静态生成
  }
})

这个配置的核心思路是“按需分配”。/products/** 用 ssr: true 加 swr: 60 表示商品列表页服务端渲染，同时接口数据 60 秒内复用，不用每次请求都重新渲染整页，相当于给 SSR 加了一层缓存，比较适合价格、库存这类数据更新要求不高的列表。购物车和结算页都是用户专属页面，搜索引擎不会收录，而且 JS 交互很重，直接用 CSR 能明显降低服务端压力。

3.3 SSR 页面的数据获取方式：useFetch 与 useAsyncData

routeRules 只是决定了“谁来渲染”，页面里的数据怎么拿也需要配合调整。SSR 模式下，最常见的数据获取方式是 useFetch 和 useAsyncData。这两个 composable 会自动在服务端发起请求、把结果渲染进 HTML，然后再在客户端水合时复用同一份数据，避免重复请求。

一个典型的 SSR 商品页面可以这样写：

vue复制<script setup lang="ts">
// 服务端和客户端都会执行，但服务端执行时会阻塞页面渲染，
// 拿到数据后才生成 HTML。
const { data: product, pending, error } = await useFetch('/api/product/10001', {
  // 这里可以配置请求头、超时等
})

// 也可以直接用 useAsyncData 包一层自定义请求
// const { data } = await useAsyncData('product', () => $fetch('/api/product/10001'))
</script>

<template>
  <div>
    <h1>{{ product?.title }}</h1>
    <p>{{ product?.description }}</p>
  </div>
</template>

这个写法有几点值得注意。第一，useFetch 请求的 URL 如果是相对路径，在服务端会发给当前站点的服务端；如果你要请求外部接口，需要写完整 URL，或者通过 runtimeConfig 配置基础地址。第二，useAsyncData 的第一个参数是 key，它决定了数据缓存的标识，同一个页面多个请求要用不同的 key，否则会互相覆盖。第三，SSR 模式下请求是阻塞式的，这意味着接口越慢，页面响应时间越长，所以一定要在服务端做好超时和错误处理。

3.4 CSR 页面的数据获取方式：onMounted 与 lazy 选项

被 routeRules 设为 ssr: false 的页面，组件里的代码只在客户端执行。数据获取的时机和方式要跟着调整。最简单的做法是把数据请求放到 onMounted 里：

vue复制<script setup lang="ts">
const cartItems = ref([])
const loading = ref(true)

onMounted(async () => {
  try {
    const res = await $fetch('/api/cart/list')
    cartItems.value = res.data
  } catch (e) {
    // 处理错误
  } finally {
    loading.value = false
  }
})
</script>

但对于 Nuxt 项目来说，更推荐仍然使用 useFetch，只是通过 lazy 选项把它变成非阻塞的：

vue复制<script setup lang="ts">
// lazy: true 表示不阻塞路由跳转，页面先渲染，数据到了再更新
const { data: cartItems, pending } = await useFetch('/api/cart/list', {
  lazy: true,
  server: false, // 确保只在客户端请求
})
</script>

这里有个细节：如果你在 SSR 页面里不小心给 useFetch 加了 server: false，初始 HTML 里就会缺少这部分数据，可能导致水合时内容不一致。反过来，在 CSR 页面里加不加 server: false 影响倒不大。我的建议是，在被 routeRules 设为 ssr: false 的页面里，统一给 useFetch 加上 server: false，让请求只发生在客户端，这样代码逻辑更明确。

3.5 一个典型混合项目的配置实战

我实际做过的一个项目是 B2B 官网加会员系统：官网部分要 SEO，会员中心是登录后的应用。我当时在 nuxt.config.ts 里这样配置：

typescript复制export default defineNuxtConfig({
  ssr: true, // 全局默认 SSR，保底
  routeRules: {
    // 官网页面：SSR，保持实时内容
    '/': { ssr: true },
    '/about': { ssr: true },
    '/blog/**': { ssr: true, swr: 3600 },
    // 会员中心：完全客户端渲染，免去每次请求的服务器渲染开销
    '/dashboard/**': { ssr: false },
    '/settings/**': { ssr: false },
    // 登录页其实不用 SEO，也可以关掉 SSR
    '/login': { ssr: false },
    '/register': { ssr: false },
    // 招聘页面很久才更新一次，直接静态生成
    '/jobs': { static: true },
  }
})

这个配置跑了大半年，体验很好。官网和博客的 SEO 收录正常，会员中心页面响应速度快，登录跳转也顺滑，服务器压力比全站 SSR 低了大概 40%。这也能说明：渲染模式不是越高级越好，而是越合适越好。

4. 客户端渲染和服务端渲染的实操差异与代码改造

4.1 SSR 下的生命周期陷阱：onMounted 和 window 对象

切到 SSR 模式后，第一波报错基本都集中在组件代码里。最典型的就是直接用 window 或 document：

vue复制<script setup lang="ts">
// 这段代码在服务端就会炸，因为 Node 里没有 window
const width = window.innerWidth
</script>

正确的做法是把访问浏览器对象的行为推迟到组件挂载后，或者用 <ClientOnly> 包裹。Nuxt 3 里处理此类问题有三个思路：

第一种，用 onMounted 包一层：

vue复制<script setup lang="ts">
const width = ref(0)
onMounted(() => {
  width.value = window.innerWidth
})
</script>

第二种，用 <ClientOnly> 组件包住只有客户端才能渲染的部分：

vue复制<template>
  <div>
    <p>这块是服务端渲染的内容</p>
    <ClientOnly>
      <UserDashboard />
    </ClientOnly>
  </div>
</template>

第三种，直接用 useWindowSize 之类的 Nuxt 内置或社区 composable，它们在内部已经处理好了服务端兼容。如果你发现自己的组件在 SSR 阶段报 window is not defined，优先用这三种方案解决，不要直接去关 SSR 逃避问题。

4.2 水合不一致问题的排查思路

水合（hydration）是 SSR 模式下非常关键的一步。服务端渲染出的 HTML 里已经包含 DOM 结构，浏览器加载 JS 后，Vue 会把事件、状态、响应式系统重新绑定到已有 DOM 上。如果服务端渲染的 HTML 和客户端初始渲染的结果不一致，Vue 就会报一个水合不匹配（Hydration mismatch）警告。

最常见的触发原因有三个。第一是用到了依赖当前时间或随机数的渲染逻辑，比如 new Date().toLocaleString()，服务端渲染的时间和客户端浏览器时间不一样。第二是在渲染过程中读取了 localStorage 或浏览器环境变量，导致内容在两端不一致。第三是第三方组件库有些组件在 SSR 下不会完整渲染，水合时必然出现差异。

最简单的规避方式就是让有差异的内容只在客户端渲染：

vue复制<template>
  <div>
    <!-- 服务端输出的内容区域 -->
    <p>服务端渲染的时间可以放这里</p>
    <!-- 只有客户端才渲染的内容 -->
    <ClientOnly>
      <p>当前准确时间：{{ currentTime }}</p>
    </ClientOnly>
  </div>
</template>

如果是第三方组件导致的水合问题，最好查一下组件库的官方文档，确认它是否支持 SSR。实在不支持的，用 <ClientOnly> 包一层也能解决。水合警告本身不会阻断页面功能，但它说明服务端和客户端的 DOM 不一致，隐藏着潜在的状态错乱风险，不要视而不见。

4.3 CSR 页面为什么会有 FOUC 和白屏问题

CSR 模式下最影响体验的问题就是 FOUC（Flash of Unstyled Content）和白屏。FOUC 是指页面先短暂闪现无样式内容、然后才应用 CSS 的情况；白屏则是 JS 还没加载完时页面一片空白。这两个问题在纯 CSR 的页面里几乎无法完全避免，但可以通过组合预取、loading 状态和路由过渡来减轻。

我常用的几个手段：第一，Nuxt 的 app.vue 里加全局 loading 指示器，让用户知道页面在加载而不是卡死。第二，关键数据请求在路由跳转前触发，把请求提前到页面切换阶段，减少等待时间。第三，静态资源开启预加载，尤其是首屏的 JS 和 CSS。第四，如果页面里有一部分内容相对固定，可以考虑把它单独做成一个静态页面，而不是全部依赖客户端渲染。

之前我做一个营销活动页，因为活动数据一个月更新一次，页面本身不需要 SSR，但又不想用户看到白屏。最后我直接用 routeRules 把活动页配成 static: true，构建时生成静态 HTML，访问时直接返回，既避免了白屏，又不占用服务器资源。这个思路在营销页、落地页、公告页等场景下非常实用。

4.4 接口调用的差异化处理：SSR 时请求怎么打、CSR 时怎么打

这是控制渲染模式时最容易出问题的地方。同样是 $fetch('/api/user/info')，在 SSR 页面里，这个请求发生在服务端；在 CSR 页面里，请求发生在浏览器。由于执行环境不同，请求的目标地址、请求头、Cookie 携带规则都不一样。

服务端请求时，如果写的是相对路径 /api/user/info，Nuxt 的 Nitro 服务会把它当成站内请求转发。如果你要请求一个外部后端服务，比如 https://api.example.com/user/info，要注意服务端环境不一定能直接访问外网，或者跨网络访问会比较慢。这时候建议在 runtimeConfig 里配置接口基础地址，通过环境变量切换：

typescript复制// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api'
    }
  }
})

// 页面里使用
const { data } = await useFetch('/user/info', {
  baseURL: useRuntimeConfig().public.apiBase
})

客户端请求时，往往需要考虑 CORS 问题。如果后端允许跨域，那浏览器直接请求没问题；如果不允许，就需要在 Nitro 层配置接口代理，让浏览器请求 Nuxt 服务，再由 Nuxt 服务转发到后端。这在部署到生产环境后尤其重要，因为浏览器环境里没有“后端同源”的概念，跨域配置不当会直接导致请求失败。

我推荐的做法是：统一在 Nitro 里配置接口代理，前端代码永远请求相对路径，由 Nuxt 服务端转发到真实后端。这样无论 SSR 还是 CSR，代码层都一致，不需要为不同模式写两套请求逻辑。

5. 实操踩坑与常见问题排查实录

5.1 Nuxt 反向代理一直报 502 错误

502 错误在我接触 Nuxt 的项目里出现频率很高，基本都是“反向代理目标不可达”导致的。这里说的反向代理不是指我们平时提到的某些工具，而是指部署架构里 Nginx 把请求转发给 Nuxt 服务时，Nuxt 服务没有正常响应，Nginx 返回 502。

排查步骤一般是：

1. 先确认 Nuxt 服务是否正常启动：直接 curl 一下 http://127.0.0.1:3000，看能不能返回 HTML。
2. 确认 Nginx 配置里的 proxy_pass 地址是否正确，端口、路径、协议（http 还是 https）都要对上。
3. 检查 Nginx 到 Nuxt 服务之间的网络，有时候是防火墙或安全组规则挡了流量。
4. 检查是否因 SSR 页面渲染慢超时，Nginx 默认的 proxy_read_timeout 是 60 秒，如果服务端渲染某个页面时调用的接口响应很慢，就容易触发超时。

这里再强调一下：SSR 页面里服务端接口慢会直接拖垮整个页面的响应速度，要特别关注服务端数据请求的耗时和超时设置。不过需要注意，这里讨论的是正常的服务代理配置问题，和任何非正常工具或方式完全无关，属于正规部署运维的常规范畴。

5.2 SSR 页面接口异常：服务端执行环境下的特殊表现

有时候同一个接口在“本地浏览器调试”没问题，部署到服务器后 SSR 页面却报错。核心原因在于 SSR 模式下这个请求是在服务器上发起的，请求来源 IP、请求头、Cookie 都跟浏览器不一样。你可能会遇到这些情况：

处理这类问题的通用做法是，在服务端请求时把关键请求头（比如 ua、cookie、authorization）透传过去。使用 useFetch 时可以通过 headers 配置：

typescript复制const { data } = await useFetch('/api/user/info', {
  headers: {
    cookie: useRequestHeaders(['cookie']).cookie || ''
  }
})

useRequestHeaders 是 Nuxt 提供的组合函数，专门用来在服务端获取当前请求的请求头。不过要注意，不是所有请求头都应该透传，敏感信息要谨慎处理，避免被客户端拿到。

5.3 水合不完全导致的事件不生效问题

有一种很隐蔽的问题：页面内容已经显示在浏览器里，看起来一切正常，但按钮点击没有反应、下拉框不展开、交互事件全部失效。这种情况大概率是水合失败了，服务端渲染的 DOM 和客户端预期的 DOM 不一致，Vue 在尝试绑定事件时干脆放弃了绑定。

排查思路是先看控制台有没有 hydration mismatch 警告。有警告就按前面 4.2 节的方法处理这类差异。如果警告不明确，可以用一个简单技巧快速定位：在怀疑出问题的组件上临时加 key 属性，强制它在客户端重新渲染。也可以直接把某个小组件用 <ClientOnly> 包住，看问题是否消失。如果包住就不出问题了，说明这个组件存在两端渲染结果不一致，需要单独处理。

5.4 创建 Nuxt 项目时报错：a complete log of this run can be found in

很多人第一次跑 npx nuxi init my-app 的时候会碰见输出类似“a complete log of this run can be found in: C:\Users\admin...”的报错。这通常不是 Nuxt 本身的问题，而是环境问题。常见原因包括 Node.js 版本过低、npm 缓存损坏、目录权限不足、或者网络原因导致依赖安装失败。

我建议按下面的顺序排查：

1. 确认 Node.js 版本，Nuxt 3 要求 Node 18 以上，Node 16 跑不起来。
2. 清掉 npm 缓存重新安装，npm cache clean --force 后删除 node_modules 和 lock 文件再跑一次。
3. 检查是否在公司网络环境下，代理或防火墙可能导致 npm 下载依赖失败。如果确实受网络限制，可以设置国内镜像源，但只在合规情况下操作。
4. 如果是 Windows 环境，路径过长也可能导致依赖安装失败，尝试把项目放在路径短的目录下。

这些看起来是创建项目阶段的小事，但很多人在第一步就卡住，反而没机会接触到渲染模式本身。环境问题解决了，后面的 SSR/CSR 调试才能顺利进行。

5.5 常用排查命令清单

最后整理一份排查清单，拿去直接用。

bash复制# 查看 Nuxt 版本和 Node 环境
node -v
npm -v
npx nuxi info

# 本地启动开发服务器，观察 SSR 日志
npm run dev

# 构建并预览生产版本，生产模式很多问题才会暴露
npm run build
npm run preview

# 查看构建产物，确认输出的是服务端产物还是静态资源
ls .output/server  # 如果存在说明是 SSR 产物
ls .output/public  # 静态资源目录

调试渲染模式相关问题时，我习惯先开生产模式预览。很多 SSR 相关的问题在 dev 模式下不会出现，因为 dev 模式有热更新、错误提示也更宽松，生产模式才是真实运行状态。遇到水合、接口、渲染表现不一致之类的怪问题，都值得先切到生产模式复测一遍。这里要想清楚：本地开发时浏览器和 Node 服务在同一个机器上，很多“通”的现象是假象，部署到真实环境后服务端和客户端彻底分离，问题才真正浮出水面。

回到开头说的那句话：控制 Nuxt 的渲染模式，核心不是会写 ssr: true 或 ssr: false，而是知道每个页面为什么需要这一种模式、切换了以后数据链路和部署方式要跟着怎么变。处理渲染模式问题的时候，我的习惯是从三个层面排查：先看是全局问题还是单页面问题，再确认数据获取方式跟模式是否匹配，最后检查部署后 Nginx、接口代理和跨域情况。这个思路基本能覆盖绝大多数 Nuxt 渲染模式引发的疑难杂症。

如果你现在正遇到某个具体页面加载慢、SEO 不上线、或者接口时不时报错，不妨先回头看一眼这个页面的渲染模式配置，再结合上面的方法逐步排查。很多时候看起来复杂的问题，根源就是渲染方式选错了。