代码 Nuxt 4.5 实验性 SSR Streaming 实测与踩坑

Nuxt 4.5 SSR Streaming 实测与踩坑笔记

2026-08 发布，底层升级幅度大，SSR Streaming 是头条特性。先说结论：这玩意是给 TTFB 用的，不是给总耗时用的。 下面记录实测结论和几个容易埋雷的点。

版本主要升级点

• 底层 Vite 升级到 Vite 8
• 新增基于 Rsbuild 的 Rspack 2 构建器，替代 Webpack，冷启动和 HMR 有明显改善
• 新增稳定错误码系统（如 NUXT_E1001）
• 新增 useLayout、named views、useFetch / useAsyncData 的响应式 enabled 选项
• Nuxt 3 已于 2026-07-31 EOL，升级 4.x 是正路

SSR Streaming 实测

一行开启：

// nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    ssrStreaming: true
  }
})

原理一句话：先把 HTML shell 立即 flush 出去改善 TTFB，正文边渲染边流式下发，类似 React Suspense 的思路。

实测记录：

• server work 总耗时没变，还是 2.5 秒左右
• 唯一变化是：浏览器在 server 还在干活的时候就能先渲染 shell，视觉上早看到了框架页
• 2.5 秒的总耗时，该等还是等

所以如果有人跟你吹「开了 streaming 就快了」，那不是真的。它只改变了「什么时候能看到东西」，不改变「什么时候东西就绪」。

坑位清单

1. shell flush 后不要再动响应头

这是最大的坑。一旦 shell flush 出去：

• late status 改不了
• header 改不了
• cookie 改不了

都到不了客户端。

会导致正确性问题而非纯性能问题的场景：

• middleware 里做鉴权
• middleware 里做重定向
• set-cookie 依赖 body 渲染后才去改响应头

这些如果原来依赖「body 渲染完成后再改响应头」的时序，streaming 开了直接变成逻辑错误，不只是慢一点。

2. 官方对爬虫自动禁用 streaming

搜索引擎和爬虫仍然收到完整 HTML，不会拿到分段的流式响应。这个不用自己配，官方行为。

3. routeRules 特定配置会回退 buffered renderer

routeRules 里如果用了以下配置之一，该路由会自动回退到 buffered renderer（即不流式）：

• redirect
• cache
• isr
• swr

// nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    ssrStreaming: true
  },
  routeRules: {
    // 这条路由会回退 buffered renderer，streaming 不生效
    '/legacy/**': { swr: 3600 }
  }
})

注意：全局开了 streaming，但 routeRules 命中上述规则的路由不会走流式，排查问题的时候先检查这里。

升级注意

升级命令：

npx nuxt upgrade --dedupe

不要跳过 dedupe，因为这次升级带动：

• unhead v3 大版本
• unctx v3 大版本

尤其 unhead v3 对 useHead 加了更严格的类型收窄，有破坏性 TS 变变更的可能性。升级后建议顺手跑一遍类型检查。

其他

• 错误码系统从「报错靠猜」变为稳定码（如 NUXT_E1001），排查问题时直接用码搜，效率高
• useLayout 与 named views 这波属于日常开发体验改善，影响面不大，这里不展开

一句话总结：streaming 是 TTFB 优化手段，不是性能银弹。开之前先确认项目里有没有「body 渲染后改响应头」的依赖，有就先重构，再开开关。