TanStack Start - 静态预渲染 (Static Prerendering)

在构建时生成静态 HTML 文件，提升性能并支持静态站点部署。静态预渲染可以向用户提供预渲染的 HTML 文件而无需动态生成，适用于文档网站、博客和营销页面等静态内容。

什么是静态预渲染

静态预渲染是为应用生成静态 HTML 文件的过程，具有以下优势：

好处	描述
更快的内容传递	预生成的 HTML 从 CDN 瞬间提供
降低服务器负载	无需为每个请求渲染页面
更低的成本	静态托管比动态服务器便宜
更好的 SEO	搜索引擎可以直接索引 HTML
离线支持	可以与 service workers 结合使用

配置预渲染

在 vite.config.ts 文件中添加 prerender 选项：

// vite.config.ts
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    tanstackStart({
      prerender: {
        enabled: true,
        autoSubfolderIndex: true,
        autoStaticPathsDiscovery: true,
        concurrency: 14,
        crawlLinks: true,
        filter: ({ path }) => !path.startsWith('/do-not-render-me'),
        retryCount: 2,
        retryDelay: 1000,
        maxRedirects: 5,
        failOnError: true,
        onSuccess: ({ page }) => {
          console.log(`Rendered ${page.path}!`)
        },
      },
      pages: [
        {
          path: '/my-page',
          prerender: { enabled: true, outputPath: '/my-page/index.html' },
        },
      ],
    }),
    viteReact(),
  ],
})

自动静态路由发现

所有静态路径将被自动发现并无缝合并与指定的 pages 配置。路由在以下情况下被排除在自动发现之外：

路径参数路由（例如 /users/$userId），因为它们需要特定的参数值
布局路由（以 _ 为前缀），因为它们不渲染独立页面
没有组件的路由（例如 API 路由）

当启用 crawlLinks 时，如果动态路由从其他页面链接，它们仍可以被预渲染。

爬取链接

当启用 crawlLinks 时（默认：true），TanStack Start 将从预渲染页面中提取链接并预渲染那些链接的页面。如果 / 包含指向 /posts 的链接，那么 /posts 也将自动被预渲染。

tsx

// src/routes/index.tsx
export const Route = createFileRoute('/')({
  component: Home,
})

function Home() {
  return (
    <div>
      <h1>Home</h1>
      <Link to="/posts">View Posts</Link>
    </div>
  )
}

选项	类型	默认值	描述
`crawlLinks`	boolean	`true`	是否爬取链接
`maxRedirects`	number	`5`	最大重定向次数
`concurrency`	number	`14`	并发预渲染作业数
`retryCount`	number	`2`	失败重试次数
`retryDelay`	number	`1000`	重试延迟（毫秒）

预渲染策略

策略 1: 全局预渲染

tsx

prerender: {
  enabled: true,
  autoStaticPathsDiscovery: true,
  crawlLinks: true,
}

策略 2: 手动指定路由

tsx

prerender: {
  enabled: true,
  autoStaticPathsDiscovery: false,
  pages: [
    { path: '/' },
    { path: '/about' },
    { path: '/contact' },
  ],
}

策略 3: 混合策略

tsx

prerender: {
  enabled: true,
  autoStaticPathsDiscovery: true,
  pages: [
    { path: '/posts/1', prerender: { enabled: true } },
    { path: '/posts/2', prerender: { enabled: true } },
  ],
}

预渲染输出结构

text

dist/
├── client/
│   ├── _shell.html
│   ├── index.html
│   ├── about/
│   │   └── index.html
│   ├── blog/
│   │   ├── index.html
│   │   └── post-1/
│   │       └── index.html
│   └── assets/
│       ├── index-[hash].js
│       └── index-[hash].css
└── server/
    └── index.mjs

选项	默认值	描述
`outputPath`	`dist/client`	静态文件输出目录
`autoSubfolderIndex`	`false`	使用 `/page/index.html` 而不是 `/page.html`

预渲染 vs 服务器渲染

特性	预渲染	服务器渲染
生成时间	构建时	请求时
性能	最快	较快
成本	低	高
数据新鲜度	构建时数据	实时数据
适用场景	静态内容	动态内容

配置速查

配置	默认值	用途
`enabled`	`false`	启用预渲染
`autoStaticPathsDiscovery`	`true`	自动发现静态路由
`crawlLinks`	`true`	爬取链接
`concurrency`	`14`	并发作业数
`retryCount`	`2`	重试次数
`filter`	-	过滤函数