跳到主要内容

Router SSR

很多人第一次意识到这一点时都会愣一下：

TanStack Router 自己就能做 SSR，而且还支持 Streaming SSR。

所以 TanStack Start 并不是“让 Router 第一次拥有服务端能力”，而是把这条能力整合成更完整的框架形态。

1. Router 自己的 SSR 能力到什么程度​

官方 SSR 文档明确把它拆成两类：

  • Non-streaming SSR
  • Streaming SSR

并且文档提供了：

  • 客户端 RouterClient
  • 服务端 RouterServer
  • createRequestHandler
  • defaultRenderHandler
  • renderRouterToString
  • renderRouterToStream

这说明它不是“理论上能 SSR”，而是真的有可用的 SSR 工具链。

一个最小客户端入口​

import { hydrateRoot } from 'react-dom/client'
import { RouterClient } from '@tanstack/react-router/ssr/client'
import { createRouter } from './router'

const router = createRouter()

hydrateRoot(document, <RouterClient router={router} />)

一个最小服务端入口​

import {
  createRequestHandler,
  defaultStreamHandler,
} from '@tanstack/react-router/ssr/server'
import { createRouter } from './router'

export async function render({ request }: { request: Request }) {
  const handler = createRequestHandler({ request, createRouter })

  return handler(defaultStreamHandler)
}

哪怕你最后不用这套手工 SSR，知道它能这样接，对理解 Start 也很有帮助。

2. 它会自动处理哪些事情​

官方文档里提到了几个很关键的自动能力：

  • 服务端自动使用适合 SSR 的 history
  • 路由 loader 数据自动脱水/注水
  • Streaming 场景下支持流式传输相关处理

这对自己搭 SSR 来说非常重要。否则很多人做着做着，就会被 hydration 和数据同步细节拖住。

3. 那为什么还需要 Start​

因为“能做 SSR”和“是一套完整全栈框架”之间，中间还差不少东西。

TanStack Start 往上补的是：

  • 更完整的项目骨架
  • Server Functions
  • Server Routes
  • Middleware
  • Hosting 指导
  • SPA Mode / Selective SSR / ISR 这套更系统的落地能力

你可以把关系理解成：

  • Router SSR 是能力底座
  • Start 是围绕这套能力搭起来的工程化封装

4. 什么时候只用 Router SSR 就够​

适合​

  • 你已经有自己的 Node/Bun/Worker 服务端壳子
  • 你只想要 Router 的 SSR，不想引入整套框架
  • 团队喜欢自己掌控服务端入口和构建流程

不太适合​

  • 你还希望有统一的 Server Functions / Server Routes
  • 你想少写入口层样板
  • 你更希望有一条成体系的全栈主线

5. 官方也提醒了一个现实问题​

官方 Router SSR 文档里有一段 warning，很值得记住：虽然他们努力把 SSR API 和 Start 分开，但底层有共享实现，所以在 Start 还没稳定到最终状态前，这部分也可能继续变化。

这句话的含义很实际：

  • 这套能力不是不能用
  • 但你最好别把它想成一块完全冻结、完全不动的老牌基础设施

如果是生产项目，版本策略要保守一点。

6. Router + Query + 自定义服务端 vs Start​

这是很多团队真正会遇到的选择。

方案一：Router + Query + 自定义服务端​

优点：

  • 自由度高
  • 能贴合现有后端架构
  • 只拿你要的部分

代价：

  • 你要自己收入口、服务端调用边界、部署整合
  • 项目越大，胶水层越容易慢慢长出来

方案二：直接用 Start​

优点：

  • 路由、服务端调用、渲染、部署建议更统一
  • 少写很多“明明每个项目都要写一遍”的工程胶水

代价：

  • 你要接受它的框架边界
  • 版本仍要关注 RC 阶段的成熟度

小结​

TanStack Router 本身就已经不只是客户端路由库。它有自己的 SSR 和 Streaming 能力。

但从“能做 SSR”走到“适合团队长期维护的全栈框架”，中间仍有很多工程问题。TanStack Start 的价值，恰好就在把这些问题收起来。