TanStack Start - Selective SSR 选择性服务端渲染

TanStack Start 的选择性 SSR 功能允许你配置哪些路由应该在服务端执行，哪些路由组件应该在服务端渲染。

什么是选择性 SSR

在 TanStack Start 中，匹配初始请求的路由默认在服务端渲染。选择性 SSR 允许你配置：

哪些路由应该在服务端执行 beforeLoad 或 loader
哪些路由组件应该在服务端渲染

与 SPA 模式的比较

特性	SPA 模式	选择性 SSR
beforeLoad/loader	完全禁用服务端执行	按路由配置
组件渲染	完全禁用服务端渲染	按路由配置
粒度	全局	每个路由
灵活性	低	高

配置

tsx

// src/start.ts
export const startInstance = createStart(() => ({
  defaultSsr: false,
}))

SSR 模式

`ssr: true` (默认)

在初始请求时：在服务端运行 beforeLoad 和 loader，在服务端渲染组件，将 HTML 标记发送到客户端进行水合。

tsx

export const Route = createFileRoute('/posts/$postId')({
  ssr: true,
  component: () => <div>此组件在服务端渲染</div>,
})

`ssr: false`

禁用服务端执行和渲染：

tsx

export const Route = createFileRoute('/posts/$postId')({
  ssr: false,
  component: () => <div>此组件在客户端渲染</div>,
})

`ssr: 'data-only'`

在服务端运行 beforeLoad 和 loader，但禁用路由组件的服务端渲染：

tsx

export const Route = createFileRoute('/posts/$postId')({
  ssr: 'data-only',
  component: () => <div>此组件在客户端渲染</div>,
})

函数形式

使用 ssr 属性的函数形式在运行时决定是否 SSR 路由：

tsx

export const Route = createFileRoute('/docs/$docType/$docId')({
  ssr: ({ params, search }) => {
    if (params.status === 'success' && params.value.docType === 'sheet') {
      return false
    }
    if (search.status === 'success' && search.value.details) {
      return 'data-only'
    }
  },
  component: () => <div>此组件在客户端渲染</div>,
})

继承规则

子路由继承其父级的选择性 SSR 配置。继承的值只能更改为更具限制性（即 true → data-only 或 false，data-only → false）。

tsx

root { ssr: undefined }      // 默认为 true
  posts { ssr: 'data-only' } // 数据在服务端，组件在客户端
     $postId { ssr: true }   // 无效，继承 'data-only'
       details { ssr: false } // 有效，覆盖为 false

使用场景

需要浏览器 API 的路由

tsx

export const Route = createFileRoute('/canvas')({
  ssr: false,
  component: CanvasEditor,
})

需要用户数据的路由

tsx

export const Route = createFileRoute('/dashboard')({
  ssr: 'data-only',
  loader: async () => fetchUserData(),
  component: Dashboard,
})

模式对比

模式	beforeLoad	loader	组件渲染	用途
`true`	服务端	服务端	服务端	完全 SSR，SEO 友好
`'data-only'`	服务端	服务端	客户端	数据预加载，客户端渲染
`false`	客户端	客户端	客户端	纯客户端，浏览器 API

模式选择指南

需求	推荐模式
SEO 重要	`true`
需要浏览器 API	`false`
数据预加载，复杂 UI	`'data-only'`
用户特定内容	`'data-only'` 或 `false`
性能敏感	`'data-only'`