代码分割 | TanStack Router React Docs

代码分割和懒加载是一种强大的技术，用于改善应用程序的包大小和加载性能。

减少初始页面加载时需要加载的代码量
代码在需要时按需加载
产生更小的代码块，浏览器可以更容易地缓存

TanStack Router 如何分割代码？

TanStack Router 将代码分为两类：

关键路由配置 - 渲染当前路由并尽早启动数据加载过程所需的代码。
- 路径解析/序列化
- 搜索参数验证
- 加载器、预加载
- 路由上下文
- 静态数据
- 链接
- 脚本
- 样式
- 下面未列出的所有其他路由配置
非关键/懒加载路由配置 - 匹配路由不需要的代码，可以按需加载。
- 路由组件
- 错误组件
- 等待组件
- 未找到组件

🧠 为什么加载器不被分割？

加载器已经是一个异步边界，所以您需要双重付出代价来获取代码块_并且_等待加载器执行。

从分类上讲，它比组件更不可能导致大的包大小。

加载器是路由最重要的可预加载资源之一，特别是如果您使用默认的预加载意图（如悬停在链接上），因此加载器在没有任何额外异步开销的情况下可用是很重要的。

了解分割加载器的缺点后，如果您仍然想继续，请转到数据加载器分割部分。

将路由文件封装到目录中

由于 TanStack Router 的基于文件的路由系统设计为支持扁平和嵌套文件结构，因此可以将路由文件封装到单个目录中，而无需任何额外配置。

要将路由文件封装到目录中，请将路由文件本身移动到与路由文件同名的目录中的 .route 文件中。

例如，如果您有一个名为 posts.tsx 的路由文件，您将创建一个名为 posts 的新目录，并将 posts.tsx 文件移动到该目录中，将其重命名为 route.tsx。

之前

posts.tsx

之后

posts
- route.tsx

代码分割的方法

TanStack Router 支持多种代码分割方法。如果您使用基于代码的路由，请跳到基于代码的分割部分。

当您使用基于文件的路由时，可以使用以下代码分割方法：

使用自动代码分割 ✨
使用 .lazy.tsx 后缀
使用虚拟路由

使用自动代码分割✨

这是代码分割路由文件最简单和最强大的方法。

当使用 autoCodeSplitting 功能时，TanStack Router 将根据上述非关键路由配置自动分割您的路由文件。

Important

自动代码分割功能仅在您使用基于文件的路由与我们的支持的打包器之一时可用。如果您仅使用 CLI (@tanstack/router-cli)，这将不会工作。

要启用自动代码分割，您只需要将以下内容添加到 TanStack Router 打包器插件的配置中：

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({
      // ...
      autoCodeSplitting: true,
    }),
    react(), // 确保在 TanStack Router 打包器插件之后添加此插件
  ],
})

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({
      // ...
      autoCodeSplitting: true,
    }),
    react(), // 确保在 TanStack Router 打包器插件之后添加此插件
  ],
})

就是这样！TanStack Router 将根据关键和非关键路由配置自动分割所有路由文件。

如果您想要对代码分割过程有更多控制，请转到自动代码分割指南以了解更多可用选项。

使用 .lazy.tsx 后缀

如果您无法使用自动代码分割功能，您仍然可以使用 .lazy.tsx 后缀来分割路由文件。这就像将代码移动到带有 .lazy.tsx 后缀的单独文件中��使用 createLazyFileRoute 函数而不是 createFileRoute 一样简单。

Important

__root.tsx 路由文件，无论使用 createRootRoute 还是 createRootRouteWithContext，都不支持代码分割，因为无论当前路由如何，它总是被渲染。

这些是 createLazyFileRoute 支持的唯一选项：

导出名称	描述
component	为路由渲染的组件。
errorComponent	在加载路由时发生错误时渲染的组件。
pendingComponent	在路由加载时渲染的组件。
notFoundComponent	如果抛出未找到错误时渲染的组件。

使用 .lazy.tsx 的代码分割示例

当您使用 .lazy.tsx 时，可以将路由分割为两个文件以启用代码分割：

之前（单个文件）

tsx

// src/routes/posts.tsx
import { createFileRoute } from '@tanstack/react-router'
import { fetchPosts } from './api'

export const Route = createFileRoute('/posts')({
  loader: fetchPosts,
  component: Posts,
})

function Posts() {
  // ...
}

// src/routes/posts.tsx
import { createFileRoute } from '@tanstack/react-router'
import { fetchPosts } from './api'

export const Route = createFileRoute('/posts')({
  loader: fetchPosts,
  component: Posts,
})

function Posts() {
  // ...
}

之后（分割为两个文件）

此文件将包含关键路由配置：

tsx

// src/routes/posts.tsx

import { createFileRoute } from '@tanstack/react-router'
import { fetchPosts } from './api'

export const Route = createFileRoute('/posts')({
  loader: fetchPosts,
})

// src/routes/posts.tsx

import { createFileRoute } from '@tanstack/react-router'
import { fetchPosts } from './api'

export const Route = createFileRoute('/posts')({
  loader: fetchPosts,
})

非关键路由配置进入带有 .lazy.tsx 后缀的文件：

tsx

// src/routes/posts.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts')({
  component: Posts,
})

function Posts() {
  // ...
}

// src/routes/posts.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts')({
  component: Posts,
})

function Posts() {
  // ...
}

使用虚拟路由

您可能会遇到这样的情况：最终从路由文件中分割出所有内容，使其变为空！在这种情况下，只需完全删除路由文件！将自动为您生成一个虚拟路由，作为代码分割文件的锚点。此虚拟路由将直接存在于生成的路由树文件中。

之前（虚拟路由）

tsx

// src/routes/posts.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts')({
  // 你好？
})

// src/routes/posts.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts')({
  // 你好？
})

tsx

// src/routes/posts.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts')({
  component: Posts,
})

function Posts() {
  // ...
}

// src/routes/posts.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts')({
  component: Posts,
})

function Posts() {
  // ...
}

之后（虚拟路由）

tsx

// src/routes/posts.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts')({
  component: Posts,
})

function Posts() {
  // ...
}

// src/routes/posts.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts')({
  component: Posts,
})

function Posts() {
  // ...
}

Tada! 🎉

基于代码的分割

如果您使用基于代码的路由，您仍然可以使用 Route.lazy() 方法和 createLazyRoute 函数来分割路由。您需要将路由配置分为两部分：

使用 createLazyRoute 函数创建懒加载路由。

tsx

// src/posts.lazy.tsx
export const Route = createLazyRoute('/posts')({
  component: MyComponent,
})

function MyComponent() {
  return <div>My Component</div>
}

// src/posts.lazy.tsx
export const Route = createLazyRoute('/posts')({
  component: MyComponent,
})

function MyComponent() {
  return <div>My Component</div>
}

然后，在您的 app.tsx 中的路由定义上调用 .lazy 方法，以导入带有非关键路由配置的懒加载/代码分割路由。

tsx

// src/app.tsx
const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/posts',
}).lazy(() => import('./posts.lazy').then((d) => d.Route))

// src/app.tsx
const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/posts',
}).lazy(() => import('./posts.lazy').then((d) => d.Route))

数据加载器分割

警告！！！ 分割路由加载器是一个危险的游戏。

它可以是减少包大小的强大工具，但正如TanStack Router 如何分割代码？部分中提到的，它是有代价的。

您可以使用路由的 loader 选项来分割数据加载逻辑。虽然此过程使得维护传递给加载器的参数的类型安全变得困难，但您始终可以使用通用的 LoaderContext 类型来帮助您：

tsx

import { lazyFn } from '@tanstack/react-router'

const route = createRoute({
  path: '/my-route',
  component: MyComponent,
  loader: lazyFn(() => import('./loader'), 'loader'),
})

// 在另一个文件中...
export const loader = async (context: LoaderContext) => {
  /// ...
}

import { lazyFn } from '@tanstack/react-router'

const route = createRoute({
  path: '/my-route',
  component: MyComponent,
  loader: lazyFn(() => import('./loader'), 'loader'),
})

// 在另一个文件中...
export const loader = async (context: LoaderContext) => {
  /// ...
}

如果您使用基于文件的路由，只有在使用带有自定义打包选项的自动代码分割时，才能分割您的 loader。

使用 getRouteApi 助手在其他文件中手动访问路由 API

正如您可能猜到的，将组件代码放在与路由不同的文件中可能会使消费路由本身变得困难。为了帮助解决这个问题，TanStack Router 导出了一个方便的 getRouteApi 函数，您可以使用它在文件中访问路由的类型安全 API，而无需导入路由本身。

my-route.tsx

tsx

import { createRoute } from '@tanstack/react-router'
import { MyComponent } from './MyComponent'

const route = createRoute({
  path: '/my-route',
  loader: () => ({
    foo: 'bar',
  }),
  component: MyComponent,
})

import { createRoute } from '@tanstack/react-router'
import { MyComponent } from './MyComponent'

const route = createRoute({
  path: '/my-route',
  loader: () => ({
    foo: 'bar',
  }),
  component: MyComponent,
})

MyComponent.tsx

tsx

import { getRouteApi } from '@tanstack/react-router'

const route = getRouteApi('/my-route')

export function MyComponent() {
  const loaderData = route.useLoaderData()
  //    ^? { foo: string }

  return <div>...</div>
}

import { getRouteApi } from '@tanstack/react-router'

const route = getRouteApi('/my-route')

export function MyComponent() {
  const loaderData = route.useLoaderData()
  //    ^? { foo: string }

  return <div>...</div>
}

getRouteApi 函数对于访问其他类型安全的 API 很有用：

useLoaderData
useLoaderDeps
useMatch
useParams
useRouteContext
useSearch