如何使用Tanstack Start实现SSR？按文档操作遇渲染异常求解答

不少开发者已经成功在最新版@tanstack/react-start中实现了Selective SSR，你可以从以下几个方向排查问题：

• 确认SSR配置启用
  检查路由组件是否正确导出selectiveSSR标识：

  // 你的路由组件文件顶部
  export const selectiveSSR = true;
  

  同时确保项目根目录的start.config.ts中全局SSR配置没有被禁用，比如：

  export default defineConfig({
    ssr: true, // 全局默认启用SSR，路由级别的selectiveSSR会覆盖这个设置
  });
  

• 规避客户端专属API
  组件中如果直接使用window、document这类仅浏览器环境存在的API，会导致SSR失败，转而降级为客户端渲染。这类代码要放到useEffect里，或者用clientOnly包裹组件：

  import { clientOnly } from '@tanstack/react-start';
  
  // 仅在客户端渲染的组件
  const ClientOnlyComp = clientOnly(() => import('./ClientOnlyComp'));
  

• 检查构建启动流程
  别用客户端模式启动项目，必须用官方命令：

  • 开发环境：npm run dev
  • 生产环境：先执行npm run build，再运行npm run start

• 正确查看页面源码
  右键页面选择「查看页面源代码」，而不是看开发者工具的「Elements」标签（后者是客户端渲染后的DOM）。如果源码里能看到组件渲染的真实HTML内容，说明SSR已经生效；如果全是JS打包代码，那就是配置没生效。

• 更新依赖版本
  确保@tanstack/react-start是最新稳定版，执行npm update @tanstack/react-start更新后再测试。

如果以上都没问题，建议检查路由定义是否规范，比如是否在routes目录下正确导出路由组件，有没有嵌套路由的配置冲突。

内容的提问来源于stack exchange，提问作者Arif Oyong