TanStack Router beforeLoad、preload 与代码分割：生产环境模式指南

本文由 Huifer 撰写，TanStack Ship 独立开发者与维护者。在发现导航到分析页面时，TanStack Query 获取初始数据期间会短暂白屏后，我在 TanStack Ship 仪表板中实现了路由预取功能。修复方案仅需两行配置：路由上的 preload 函数，以及在组件渲染前运行的数据加载器。页面感知加载时间从 400ms 降至 100ms 以内。beforeLoad 钩子是第一个添加的功能——在登录页面上线之前就加上了。本指南结合生产环境实际代码，详解这两个模式。

验证来源：TanStack Router beforeLoad 文档 · TanStack Router 预加载 · TanStack Router 代码分割最后更新：2026-09-18 · 更新日志

TL;DR: 三个消除导航加载态的 TanStack Router 模式：(1) beforeLoad 实现鉴权守卫——组件渲染前重定向；(2) preload 预加载数据——用户点击前就取好数据；(3) 路由树自动代码分割——零配置。每个模式实现时间不超过 30 分钟。

三个导航问题

TanStack Router 解决了其他路由库处理得不好的三个导航问题：

鉴权守卫：未认证用户在受保护页面渲染前重定向——而非之后
数据预加载：在用户点击前获取路由数据，导航体验即时响应
代码分割：只加载用户访问路由的代码——而非整个应用

模式一：beforeLoad 实现鉴权守卫

beforeLoad 钩子是进行身份验证检查的正确位置。它在路由的 loader 和组件之前运行——如果你从 beforeLoad 中重定向，两者都不会执行。

typescript

import { Route } from './routeTree'
import { redirect } from '@tanstack/react-router'

// 定义一次 auth 检查
async function requireAuth() {
  const user = await getCurrentUser()
  if (!user) {
    throw redirect({ to: '/login', search: { redirectTo: window.location.pathname } })
  }
  return user
}

// 应用于任何需要保护的路由
const dashboardRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/dashboard',
  beforeLoad: async () => {
    await requireAuth()
  },
  loader: async ({ context }) => {
    // context.user 在此可用，因为 beforeLoad 已设置
    const data = await fetchDashboardData(context.user.id)
    return { data }
  },
  component: DashboardPage,
})

核心要点：beforeLoad 可以设置 loader 和组件消费的 context。在 beforeLoad 中设置 user，在 loader 中读取：

typescript

const dashboardRoute = new Route({
  path: '/dashboard',
  beforeLoad: async ({ context }) => {
    const user = await getCurrentUser()
    if (!user) {
      throw redirect({ to: '/login' })
    }
    return { user } // 这会成为 context 的一部分
  },
  loader: async ({ context }) => {
    // context.user 在此有类型且可用
    return fetchDashboardData(context.user.id)
  },
})

TypeScript 类型推断：loader 中的 context.user 类型是从 beforeLoad 返回值推断出来的。无需手动类型转换。

模式二：路由预加载

预加载在导航完成前运行数据获取器或代码。结果：导航体验即时响应，因为数据已经在缓存中。

preload 函数

typescript

import { Route, preloadQuery } from '@tanstack/react-router'
import { queryClient } from './queryClient'

const productsRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/products',
  loader: async () => {
    return queryClient.ensureQueryData({
      queryKey: ['products'],
      queryFn: () => fetchProducts(),
    })
  },
  component: ProductsPage,
})

// preload 函数在导航完成前调用
const productsLink = () => {
  const preload = () => productsRoute.load()
  return (
    <Link
      to={productsRoute.fullPath}
      onMouseEnter={preload}
      onFocus={preload}
    >
      Products
    </Link>
  )
}

onMouseEnter 在点击前 50–200ms 触发。loader 在这个时间窗口内运行。当用户点击时，数据已在 TanStack Query 缓存中。

路由树预取

TanStack Router 的路由树可以预取整个子树：

typescript

// 预取 dashboard 路由及其子路由的所有数据
dashboardRoute.preload({
  // 预取所有子路由
  includeDescendants: true,
})

对于有多标签页的仪表板，当用户悬停在仪表板链接上时，这会预加载所有标签页数据。

预加载时机

preload 钩子与 TanStack Query 的后台重新获取集成：

typescript

const analyticsRoute = new Route({
  path: '/analytics',
  loader: async ({ preload }) => {
    // 如果调用了 preload，数据可能已过期——仍重新获取
    if (preload) {
      return queryClient.fetchQuery({
        queryKey: ['analytics'],
        queryFn: () => fetchAnalytics(),
        staleTime: 0, // 预加载后始终新鲜
      })
    }
    // 正常导航：有新鲜数据则使用缓存
    return queryClient.ensureQueryData({
      queryKey: ['analytics'],
      queryFn: () => fetchAnalytics(),
      staleTime: 1000 * 60 * 5, // 5 分钟
    })
  },
})

模式三：自动代码分割

TanStack Router 通过路由树自动处理代码分割。无需 Webpack 配置。

懒加载路由组件

typescript

import { Route, lazy } from '@tanstack/react-router'

const heavyRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/reports',
  // lazy() 自动代码分割组件
  component: lazy(() => import('./ReportsPage')),
})

const settingsRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/settings',
  component: lazy(() => import('./SettingsPage')),
})

组件仅在路由匹配时加载。每个路由是 bundle 中的独立分块。无需 React.lazy，无需配置 Suspense 边界——路由库自动处理。

懒加载加预取

将懒加载与预加载结合，实现即时导航体验：

typescript

const reportsRoute = new Route({
  path: '/reports',
  component: lazy({
    loader: () => import('./ReportsPage'),
    // 路由匹配时预取组件
    preload: true,
  }),
})

设置 preload: true 后，组件分块在路由匹配时就开始下载——在组件渲染之前。

Bundle 分析

添加懒加载路由后，检查你的 bundle：

bash

npx vite-bundle-visualizer

你应该看到每个懒加载路由的独立分块。典型的 TanStack Router + lazy 配置：

分块	大约大小	加载时间
主 bundle（shell + root）	~45KB	即时
Dashboard 分块	~22KB	导航时
Reports 分块	~38KB	导航时
Analytics 分块	~51KB	导航时

shell 首先加载。每个路由按需加载。只访问仪表板的用户永远不会加载 analytics 分块。

三合一组合：受保护的仪表板

typescript

import { Route, lazy, redirect } from '@tanstack/react-router'
import { queryClient } from './queryClient'

const dashboardRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/dashboard',
  beforeLoad: async ({ preload }) => {
    const user = await getCurrentUser()
    if (!user) {
      throw redirect({ to: '/login' })
    }
    return { user }
  },
  loader: async ({ context, preload }) => {
    // 如果已预取，立即使用。否则等待。
    return queryClient.ensureQueryData({
      queryKey: ['dashboard', context.user.id],
      queryFn: () => fetchDashboard(context.user.id),
      staleTime: preload ? 0 : 1000 * 60 * 2,
    })
  },
  component: lazy(() => import('./DashboardPage')),
})

// 导航组件，悬停时预加载
function DashboardLink() {
  return (
    <Link
      to={dashboardRoute.fullPath}
      onMouseEnter={() => dashboardRoute.load()}
      onFocus={() => dashboardRoute.load()}
    >
      Dashboard
    </Link>
  )
}

结果：beforeLoad 在路由加载前运行 → auth 检查 → loader 使用 context 运行 → 组件从缓存渲染数据。导航体验即时响应。

生产环境性能结果

在 TanStack Ship 仪表板中实现全部三个模式后：

指标	优化前	优化后
Dashboard 导航感知加载时间	380ms	60ms
Analytics 导航感知加载时间	520ms	80ms
主 bundle 大小	82KB	45KB
Dashboard 分块大小	—	22KB
鉴权守卫白屏（未认证）	无	无

Dashboard 导航 320ms 的提升完全来自 ensureQueryData——数据在悬停时已预取。用户点击的是热链接。

生产环境检查清单

在 beforeLoad 中实现鉴权守卫——而非组件的 useEffect 中
关键导航链接上添加预加载——主导航的 onMouseEnter
重量级路由使用懒加载组件——/reports、/analytics、/settings
懒加载设置后做 bundle 分析——验证分块是独立的
beforeLoad context 已类型化——验证 TypeScript 在 loader 中推断 context 类型

TanStack Ship 预配置了 TanStack Router，包含鉴权守卫、懒加载路由组件和 TanStack Query 集成。 查看 TanStack Router 配置和完整功能列表。