用途
本技能介绍 TanStack Start 的部署与渲染配置，覆盖托管平台接入、SSR 控制、静态预渲染以及 SEO 相关能力。TanStack Start 通过 Vite 与 Nitro 部署到任意托管服务商。
托管平台配置
Cloudflare Workers
安装依赖：
pnpm add -D @cloudflare/vite-plugin wrangler
在 vite.config.ts 中引入 cloudflare 插件（viteEnvironment 设为 ssr）、tanstackStart() 与 viteReact()。wrangler.jsonc 需设置 name、compatibility_date、compatibility_flags（含 nodejs_compat）以及 main 为 @tanstack/react-start/server-entry。
部署命令：npx wrangler login && pnpm run deploy
注意：Worker 环境变量按请求注入。模块作用域下的 process.env.X 即使在服务端也会得到 undefined。Cloudflare 规范做法是使用 cloudflare:workers 的 env 绑定（import { env } from 'cloudflare:workers'），或在 .handler() / 中间件 .server() 中按请求读取 process.env.X。
Netlify
安装依赖：
pnpm add -D @netlify/vite-plugin-tanstack-start
在 vite.config.ts 中引入 tanstackStart()、netlify() 与 viteReact()。
部署命令：npx netlify deploy
Nitro（Vercel、Railway、Node.js、Docker）
安装依赖：
npm install nitro@npm:nitro-nightly@latest
在 vite.config.ts 中引入 tanstackStart()、nitro() 与 viteReact()。
构建与启动：npm run build && node .output/server/index.mjs
Bun
Bun 部署需要 React 19；若使用 React 18，请改用 Node.js 部署。在 nitro 插件中传入 { preset: 'bun' }。
选择性 SSR
通过路由的 ssr 属性按路由控制 SSR：
ssr: true（默认）：在服务端运行beforeLoad与loader，并在服务端渲染组件。ssr: false：禁用服务端执行beforeLoad/loader与服务端渲染，仅在客户端运行。ssr: 'data-only'：在服务端运行beforeLoad/loader，但组件仅在客户端渲染。- 函数形式：可根据 params/search 在运行时决定 SSR，例如根据
params.value.docType === 'sheet'返回false。
SSR 继承规则：子路由继承父路由的 SSR 配置，且只能更严格。true 可变为 data-only 或 false；false 不能变为 true（父级 false 优先）。
默认 SSR：可在 src/start.ts 中通过 createStart(() => ({ defaultSsr: false })) 修改所有路由的默认值。
静态预渲染
在 tanstackStart 中配置 prerender：enabled、crawlLinks、concurrency、failOnError。静态路由会被自动发现；动态路由（如 /users/$userId）需要 crawlLinks 或显式 pages 配置。
SEO 与 Head 管理
- 基础 meta 标签：在路由的
head中返回meta数组，包含title、description等。 - 基于 loader 数据的动态 meta：
head: ({ loaderData }) => ({ meta: [...] })，可设置og:title、og:image等。 - 结构化数据（JSON-LD）：在
head的scripts中返回type: 'application/ld+json'与序列化后的对象。 - 动态 sitemap：通过服务端路由（如
src/routes/sitemap[.]xml.ts）的server.handlers.GET返回 XML 响应。
常见错误
- 高：Cloudflare Workers 缺少
nodejs_compat标志，导致 Node.js API 在运行时失败。 - 中：Bun 部署搭配 React 18。Bun 专用部署仅支持 React 19，React 18 请使用 Node.js 部署。
- 中：子路由放宽父级 SSR 配置。父级设为
ssr: false时，子级设ssr: true会被忽略；子级只能更严格（如父级data-only，子级false）。
跨模块引用
start-core/server-routes：用于 sitemap、robots.txt 的 API 端点。start-core/execution-model：SSR 影响代码运行位置。