TanStack Router 虚拟文件路由生成错误分析与解决方案

问题背景

在使用TanStack Router（原React Location）进行项目开发时，开发者可能会遇到一个典型问题：当项目中同时使用文件系统路由和虚拟文件路由时，执行tsr generate命令会出现TypeError: nodes.map is not a function错误。这种情况特别容易发生在Nx等Monorepo项目中。

错误现象

具体错误表现为：

1. 在包含__virtual.ts文件的项目目录中运行tsr generate命令
2. 控制台抛出nodes.map is not a function类型错误
3. 路由树生成失败

根本原因分析

经过技术分析，这个问题主要由以下两个因素共同导致：

1. 配置隔离：tsr.config.json配置文件与虚拟路由定义文件(__virtual.ts)之间存在信息隔离。生成器仅读取tsr.config.json中的配置，而忽略了虚拟路由定义。

2. 模块系统冲突：在CommonJS环境下，虚拟路由模块的导入可能存在问题，导致路由节点无法被正确解析为数组。

解决方案

方案一：使用MTS扩展名（推荐）

将虚拟路由定义文件从__virtual.ts重命名为__virtual.mts。这个简单的修改可以强制TypeScript以ES模块方式处理文件，避免CommonJS环境下的解析问题。

// __virtual.mts
import { defineVirtualSubtreeConfig } from '@tanstack/virtual-file-routes';

export default defineVirtualSubtreeConfig(async () => [
  // 路由定义
]);

方案二：配置同步

手动保持tsr.config.json与虚拟路由定义的同步：

{
  "routesDirectory": "./src/pages",
  "generatedRouteTree": "./src/routeTree.gen.ts",
  "routeFileIgnorePrefix": "-",
  "routes": {
    // 这里需要与__virtual.ts内容保持一致
  }
}

方案三：项目级配置调整

在项目根目录的package.json中设置：

{
  "type": "module"
}

此方案会强制整个项目使用ES模块系统，可能影响其他依赖，需谨慎评估。

最佳实践建议

1. 统一模块系统：推荐整个项目统一使用ES模块或CommonJS，避免混用。

2. 配置集中管理：考虑将路由配置集中到单一源（如全部使用tsr.config.js），避免分散配置。

3. 版本兼容性检查：确保@tanstack/router-generator与@tanstack/virtual-file-routes版本兼容。

4. 构建工具集成：如果使用Vite等构建工具，确保插件配置与路由配置一致。

技术原理深入

虚拟文件路由的工作原理涉及两个阶段：

1. 路由收集阶段：生成器扫描文件系统并解析虚拟路由定义
2. 路由树生成阶段：将收集到的路由信息转换为类型安全的RouteTree

当使用.ts扩展名时，在CommonJS环境下模块导出可能被错误包装，导致defineVirtualSubtreeConfig返回的不是预期的数组结构。而.mts扩展名明确指示TypeScript使用ES模块系统，避免了这种包装行为。

总结

TanStack Router的虚拟文件路由功能为开发者提供了灵活的路由组织方式，但在特定环境下可能遇到生成错误。通过理解其工作原理和模块系统的影响，开发者可以采取适当的解决方案。推荐优先使用.mts扩展名方案，它既保持了代码的清晰性，又避免了侵入性的项目配置修改。