TanStack Router预渲染与baseUrl配置问题解析

在TanStack Router项目中，开发者在使用预渲染(prerender)功能时可能会遇到一个常见问题：当配置了baseUrl后，预渲染生成的HTML文件无法正常输出。本文将深入分析这个问题及其解决方案。

问题现象

当开发者在app.config.ts中配置如下选项时：

{
  server: {
    baseURL: "/start-prerender",
    prerender: {
      routes: ['/'],
      crawlLinks: true,
    },
  },
}

构建应用后，预期的HTML文件（如index.html或start-prerender.html）不会出现在.output/public目录中。同样的问题也会出现在为路由配置baseUrl的情况下。

问题本质

这个问题的核心在于预渲染机制与baseUrl配置之间的协调问题。当设置了baseUrl后，构建系统在生成静态文件时，路径解析逻辑出现了偏差，导致无法正确输出HTML文件。

解决方案

经过实践验证，可以采用以下配置方式解决此问题：

{
  routers: {
    client: {
      base: '/shadcn-tanstack-form', 
    }
  },
  server: {
    prerender: {
      routes: ['/'],
      crawlLinks: true,
    },
  },
}

这种配置方式将baseUrl的设置从server部分移到了routers.client部分，同时保持了预渲染的配置。这种分离式的配置更符合TanStack Router的设计理念。

注意事项

1. 资源加载问题：即使HTML文件生成正确，仍可能遇到JavaScript脚本无法加载的问题。这是因为baseUrl不仅影响路由，还影响静态资源的引用路径。

2. GitHub Pages部署：对于需要部署到GitHub Pages的场景，这种配置方式特别适用，因为GitHub Pages通常要求项目名称作为URL的一部分。

3. 路径一致性：确保所有路由和资源引用都基于相同的base路径，避免混合使用不同基准路径导致的404错误。

最佳实践建议

1. 对于静态站点生成(SSG)项目，推荐将baseUrl配置在routers.client部分而非server部分。

2. 在开发环境和生产环境使用不同的baseUrl时，可以通过环境变量来动态设置。

3. 预渲染后，建议手动检查生成的HTML文件中的资源引用路径是否正确。

通过理解这些配置差异和潜在问题，开发者可以更有效地利用TanStack Router的预渲染功能，特别是在需要特定baseUrl的部署场景中。