NuxtJS 3中如何混合使用SSR与静态内容生成？

Nitro的混合渲染能力是原生内置的，相关配置藏在Nitro的路由规则模块说明里，没有单独做特性宣传，所以很多人找不到相关参考。下面直接说实现方法、适用场景、限制和常见问题：

具体实现步骤 #

核心是通过Nitro的routeRules按路由粒度指定渲染模式，不需要额外安装依赖。

• 全局基础配置
  先在配置文件里设置全局默认渲染模式，再针对不同路径单独指定规则：

// nuxt.config.ts
export default defineNuxtConfig({
  ssr: true, // 全局默认开SSR，作为未匹配规则路由的兜底渲染模式
  nitro: {
    routeRules: {
      // 产品目录类路径走实时SSR
      '/catalog/**': { ssr: true },
      // 产品规格详情类路径走构建时静态预生成
      '/product/spec/**': { prerender: true },
      // 其他路径可按需配置，比如首页、关于页这类固定页也可以设为预渲染
      '/': { prerender: true }
    }
  }
})

配置完成后执行nuxt build，Nitro会自动在构建阶段爬取所有标记prerender: true的路由，生成静态HTML文件存到产物目录；标记ssr: true的路由不会在构建时生成页面，会保留服务端渲染逻辑，等到用户请求时再实时计算返回内容。

• 动态路由预生成配置
  如果标记预渲染的是动态路由（比如/product/spec/[id]），需要提前把所有需要生成静态页的具体路径告诉Nitro，不然构建时不会自动爬取所有动态路径：

// nuxt.config.ts 补充预渲染路径配置
export default defineNuxtConfig({
  // ...其余配置省略
  nitro: {
    prerender: {
      // 支持同步返回路径数组，也支持异步拉取（比如从业务接口拉取全量需要预生成的产品ID）
      urls: async () => {
        // 示例：从内部接口拉取所有在售规格产品的ID，拼接成路径
        // const validSpecIds = await $fetch('http://内部业务接口/get-all-on-shelf-spec-ids')
        // return validSpecIds.map(id => `/product/spec/${id}`)
        return ['/product/spec/1001', '/product/spec/1002', '/product/spec/1003']
      }
    },
    routeRules: {
      '/product/spec/**': { prerender: true }
    }
  }
})

• 单页面粒度配置
  除了全局配置，也可以直接在页面文件内通过defineRouteRules宏指定当前页面的渲染规则，优先级高于全局配置：

<!-- pages/product/spec/[id].vue -->
<template>
  <!-- 页面业务内容 -->
</template>

<script setup lang="ts">
// 直接指定当前页走预渲染，无需额外引入宏，Nuxt会自动识别
defineRouteRules({
  prerender: true
})
</script>

适用场景 #

• 内容更新频率差异明显的站点：比如业务需要的产品目录、搜索结果、用户中心这类需要实时拉取数据、内容变动频繁的页面用SSR，兼顾SEO和数据实时性；产品规格、帮助文档、活动落地页这类内容长期固定、生成时需要消耗大量计算资源的页面用静态预生成，构建时一次计算，访问时直接返回静态文件，不占用服务端CPU资源。
• 性能分层需求明确的站点：流量占比高、转化路径核心的固定页面用静态生成，TTFB可以压到50ms以内，比SSR的响应速度快3-10倍；需要个性化展示、数据实时性要求高的页面用SSR，平衡体验和业务需求。
• 成本敏感的部署场景：静态生成的页面可以直接托管到CDN，只有少量SSR路由需要占用服务器计算资源，相比全站SSR可以降低70%左右的服务器成本。

使用限制 #

• 路由规则仅支持通配符匹配：**匹配任意多层路径，*匹配单层路径，不支持复杂正则匹配；规则优先级随路径精确度提升，比如/product/spec/1001的规则会覆盖/product/spec/**的通用规则。
• 动态路由预生成必须明确传参：标记了prerender: true的动态路由，如果没有在prerender.urls里列出具体路径，构建阶段不会生成对应静态文件，用户访问时会走兜底渲染模式，和预期不符。
• 预渲染内容不支持自动更新：静态页面在构建时就已经生成完毕，上线后如果对应的数据变更，必须重新执行构建流程才能更新内容，原生不支持增量静态再生（如果需要ISR能力要自己写逻辑扩展）。
• 全局SSR关闭时混合规则失效：如果设置了全局ssr: false（纯客户端渲染模式），所有路由规则里的ssr、prerender配置都会失效，所有页面都会走客户端渲染。

可能引发的问题 #

• 公共内容缓存不一致：如果静态页和SSR页共用了公共组件（比如顶部导航、活动banner、用户状态模块），很容易出现静态页的公共内容是构建时的旧版本，SSR页是实时拉取的新版本，导致用户在不同页面切换时看到的公共内容不一致，这类公共动态内容需要改成客户端挂载后再拉取最新数据。
• 路径漏配导致的渲染异常：如果动态路由的预生成路径枚举不全，用户访问未被预生成的路径时，要么触发404，要么意外走SSR逻辑，导致这部分页面的性能、渲染结果和预期不符，上线前需要全量爬取路由校验每个路径的渲染模式是否符合配置。
• 水合不匹配报错：预渲染页面的服务端逻辑是在构建阶段执行的，如果代码里依赖了运行时的服务端内存数据、临时环境变量，很容易在客户端水合时出现DOM结构不匹配的报错，预渲染页面的服务端逻辑必须保证可以在构建环境下独立执行，不依赖运行时的服务端状态。
• 资源路径404：如果静态资源和SSR服务部署在不同域名下，需要单独配置预渲染页面的资源公共路径，不然静态页里引用的CSS、JS、图片资源会出现路径错误导致加载失败。

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