用途 本技能聚焦 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: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:需要 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。SSR 配置可继承,子路由只能比父路由更严格:true 可降为 data-only 或 false,但 false 不能被升级为 true(父级 false 优先生效)。在 src/start.ts 中可通过 createStart 的 defaultSsr 修改所有路由的默认值。
静态预渲染 在 tanstackStart 配置中设置 prerender:enabled、crawlLinks、concurrency、failOnError。静态路由会自动发现;动态路由(如 /users/$userId)需要 crawlLinks 或显式 pages 配置。
SEO 与 Head 管理 可在路由 head 中定义基础 meta 标签(title、description),也可从 loaderData 生成动态 meta(如 title、description、og:title、og:image)。支持通过 scripts 输出结构化数据(JSON-LD)。可通过服务端路由(如 src/routes/sitemap[.]xml.ts)动态生成 sitemap.xml。
常见错误
- 高危:Cloudflare Workers 缺少 nodejs_compat 标志,导致 Node.js API 运行时失败。
- 中危:在 React 18 下使用 Bun 部署(Bun 专用部署仅支持 React 19,React 18 请用 Node.js 部署)。
- 中危:子路由放宽父路由的 SSR 配置(父级 false 优先生效,子路由只能更严格)。
交叉引用 start-core/server-routes:用于 sitemap、robots.txt 的 API 端点;start-core/execution-model:SSR 影响代码运行位置。
限制 文档未提供各托管平台的价格与配额信息,也未提供具体的性能数据或效果对比。