@tanstack/virtual-file-routes 是 TanStack Router 的配套包，用于以编程方式构建路由树，而不是依赖文件系统约定。适合需要显式控制路由结构、混合虚拟与物理路由，或在基于文件的路由目录中定义路由子树的场景。仅当项目配置包含 virtualRouteConfig、虚拟路由配置文件或 __virtual.ts 时使用；普通的文件路由改动属于 Router Core 与 Router Plugin。
主要能力：rootRoute(file, children?) 创建虚拟路由树根；index(file) 创建索引路由（父路径精确匹配时默认渲染）；route(path, ...) 创建路由节点，支持叶子（路径+文件）、分支（路径+文件+子节点）与仅路径前缀（无文件，用于分组子路由）三种签名；layout(file, children) 或 layout(id, file, children) 创建无路径布局路由，包裹子路由但不增加 URL 段；physical(pathPrefix, directory) 或 physical(directory) 将基于文件的路由目录挂载到 URL 前缀下，目录内沿用标准文件路由约定；defineVirtualSubtreeConfig(config) 是用于 __virtual.ts 的类型辅助恒等函数。
使用方式：安装 npm install @tanstack/virtual-file-routes；在路由配置中导入并使用上述 API 构建树，再传给 TanStack Router 插件，如 vite.config.ts 中 tanstackRouter({ target: 'react', virtualRouteConfig: routes }) 或 virtualRouteConfig: './routes.ts'。文件路径相对于插件配置的 routesDirectory（默认 ./src/routes），不要用绝对路径或项目根相对路径。physical() 传入的目录必须存在于 routesDirectory 内并遵循文件路由约定。layout() 不增加 URL 段，不要与 route() 混淆。修改虚拟树后应确认只有一个 rootRoute、所有引用文件存在、无重复有效路径或 ID、physical() 目录只挂载一次且不与虚拟子路由重叠，重新生成 routeTree.gen.ts 并检查父子关系、完整路径与导入，不要编辑生成产物，随后更新链接、重定向、参数与 from 收窄，并运行生成器测试、类型测试与生产构建。资料未提供收费、价格、平台支持范围等信息。