Skip to content

路由级数据加载:把请求瀑布流拆成一片湖 ​

学完能验收的四条 ​

  • 能画出三层嵌套路由下 onMounted 取数的时序图,并指出哪一段等待是被组件挂载顺序强制的
  • 能判断一个页面该不该迁到 Data Loader,说得出"迁了不会变快"的三种情形
  • 会给 loader 补上取消、预期错误、鉴权三处处理,不依赖默认行为
  • 能在四种取数方案之间做出选择,并解释为什么选了其中一种

版本前提先说清楚,因为这一块的坑多半出在版本上:Vue Router 5.0.0 于 2026-01-29 发布,截至 2026 年 11 月 16 日最新是 5.5.1(2026-11-13 发布),4.x 线仍在维护(4.6.5)。Data Loaders 到本文写作时依然从 vue-router/experimental 导入,官方把它放在实验性子路径下,说明 API 还有调整空间。API 细节以官方 Data Loaders 指南 与 experimental 子路径的导出说明 为准,本文写作后如有变动,以文档为准。这意味着可以在内部中后台先跑,但要有"接口改名了要跟着改"的心理准备,别在对外承诺了交付期的项目上豪赌。

1. 这一节在整个类目里的位置 ​

路由这一层有三个职责,很多团队把它们混在一起写,最后谁也说不清一个页面为什么慢。分开看就清楚了:导航守卫管"能不能去",Data Loader 管"去之前要准备什么数据",组件管"数据到了怎么画"。

先记住一句话:本篇所有内容都在回答同一个问题——页面从"自己取数"变成"路由取数",哪些问题消失了,哪些问题换了一种形式冒出来。

2. 导入案例:一次点击之后的两秒空白 ​

2026 年 9 月,一个做设备巡检的系统找到我们。订单详情页 /orders/42 点进去要等 2.1 秒才出现内容,用户反馈"点了没反应"。

打开代码,结构是这样的:父路由组件 OrderLayout 在 onMounted 里请求订单主表,拿到 customerId 之后才渲染子路由 CustomerCard,而 CustomerCard 在自己的 onMounted 里请求客户信息。再往下还有一层 ContractList,依赖客户 ID。

三段请求,每段都要等上一段的组件挂载完成。后端每个接口的 RT 都在 300ms 到 500ms 之间,单看哪个接口都不算慢。

问题不在接口,在它们被强制排了队。你可能会想:"那把三个请求都塞进父组件不就行了?"这确实能解决串行,但代价是父组件要提前知道所有子路由需要什么数据——这条耦合会在第三次加子页面时反噬你。

3. 三个概念,三种反例 ​

3.1 瀑布流:串行,而不是慢 ​

瀑布流的成因是依赖关系被组件的挂载顺序表达了出来。组件必须先存在,才能在 setup 或 onMounted 里发请求;子组件又必须等父组件渲染出来。这条链条是 Vue 的渲染模型决定的,不是谁写错了。

反例:以为"把请求挪到 onBeforeMount 就能并行"。挪了之后请求确实早了几十毫秒发出,但它依然在组件树上,父子依赖没变,水管还是那根水管。

3.2 loader:一个挂在路由上的纯取数函数 ​

loader 的定义方式是"在页面组件里定义并具名导出"。导出这一步是硬要求,路由靠 export 出来的东西才能收集到它;不导出,它就退化成普通 composable,导航阶段不会等它。

vue
<!-- src/pages/orders/[id].vue -->
<script lang="ts">
// 前提:vue-router@5.5.1;loader 在 setup 之外定义,不能有响应式副作用
import { defineBasicLoader } from 'vue-router/experimental'
import { fetchOrder } from '@/api/orders'

export const useOrder = defineBasicLoader('/orders/[id]', async (to, { signal }) => {
  return await fetchOrder(String(to.params.id), { signal })
})
</script>

<script setup lang="ts">
const { data: order, isLoading, error, reload } = useOrder()
</script>

<template>
  <div v-if="isLoading">加载中…</div>
  <div v-else-if="error">
    <p>{{ error.message }}</p>
    <button @click="reload()">重试</button>
  </div>
  <OrderDetail v-else-if="order" :order="order" />
</template>

反例:在 loader 里写 ref() 或 watch()。loader 是纯取数函数,入参只有目标路由和上下文,它的返回值会被路由打包提交,响应式对象在这里没有意义,只会让"数据什么时候生效"变得不可预测。

3.3 pack:一次导航的原子提交 ​

这是 Data Loader 相对"在守卫里手动 await"最实质的优势,也是最容易被略过的一条。

一次导航中收集到的所有 loader 被视为一个 pack。只要有一个失败或导航被取消,任何结果都不会被采用;只有全部成功,数据才一次性提交。所以你永远不会看到"头部是新的、列表还是旧的"这种中间态。

反例:以为把慢接口拆成 lazy loader 能改善首屏。不能。lazy loader 很快返回,它的数据也要等整批就绪才更新,它只减少导航阻塞时间,不改善首屏。

4. 动手任务:把三段串行改成一次并行 ​

任务目标:把案例里的三层路由改成路由级取数,并验证耗时变化。

第一步,装插件。顺序不能反——DataLoaderPlugin 必须在 router 之前注册,因为初始导航由 app.use(router) 触发:

ts
// src/main.ts
// 前提:vue-router@5.5.1,Data Loaders 仍在 experimental 子路径
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { DataLoaderPlugin } from 'vue-router/experimental'
import { routes } from './routes'
import App from './App.vue'

const router = createRouter({ history: createWebHistory(), routes })

const app = createApp(App)
app.use(DataLoaderPlugin, { router })  // ← 必须在 router 之前
app.use(router)
app.mount('#app')

预期输出:无报错,页面照常渲染。如果顺序写反,你会看到初始导航没有等待任何 loader——不报错,只是第一个页面直接闪出空状态。这个错误的表现是"看起来生效了一半",最难查。

第二步,在子页面里导出 loader,把 customerId 依赖消掉:

vue
<!-- src/pages/orders/[id]/customer.vue -->
<script lang="ts">
import { defineBasicLoader } from 'vue-router/experimental'
import { fetchCustomer } from '@/api/customer'

// 用同一个路由模式注册,两个 loader 之间没有数据依赖 → 并行执行
export const useCustomer = defineBasicLoader('/orders/[id]', async (to) => {
  return await fetchCustomer(String(to.params.id))
})
</script>

预期输出:Network 面板里订单和客户两个请求几乎同时发出,首屏从 2.1 秒降到约 0.9 秒(单个接口 RT 的上下界)。

这里容易卡住:defineBasicLoader 的第一个参数可以传路由模式也可以省略,两种写法官方文档里都存在。带路径会把路由显式写出来,可读性好,接类型化路由时也更省事;运行时语义没有区别。一个仓库里选一种,别混用——混用之后你没法 grep 出某个页面到底有几个 loader。

第三步,验证行为。从 /orders/41 跳到 /orders/42 时,导航会被推迟到数据返回之后才提交。用户点击后页面会"停"在原地一小会儿。

这不是 bug,是这套模型的固有代价。要缓解就配全局进度条,或者对非关键区域改用 lazy loader。

5. 三处必须显式写,默认行为会教你做人 ​

取消。上下文对象带 AbortSignal。导航被新导航取代或取消时信号 abort,把它传给 fetch 才能真正中断请求。不传的话旧请求会跑完,虽然这批数据不会被采用,但服务端压力是实打实的。

错误。默认所有抛出的错误都算意外错误,会中止导航并交给 router.onError(),页面根本渲染不出来,你也就看不到 error。希望页面本地展示错误,必须显式声明预期错误类型。

权限。不要用 loader 做鉴权。loader 是数据层,鉴权属于导航守卫,职责分开才不会互相等待。

ts
// src/pages/admin/dashboard.vue 的 loader 部分
// 前提:vue-router@5.5.1
import { defineBasicLoader, reroute } from 'vue-router/experimental'

class ApiError extends Error {
  override name = 'ApiError'
  constructor(message: string, public status: number) { super(message) }
}

export const useDashboard = defineBasicLoader(
  '/admin',
  async (to, { signal }) => {
    // inject / store 必须在第一个 await 之前调用
    const res = await fetch('/api/admin/stats', { signal })
    if (res.status === 401) reroute('/login')  // 内部抛异常,后面不会执行
    if (!res.ok) throw new ApiError('统计接口失败', res.status)
    return res.json()
  },
  { errors: [ApiError] },  // 声明为预期错误:不中止导航,落进 error
)

reroute() 的语义值得单独记:它内部抛异常,调用后不需要 return,也不接受 true 或 undefined,因为那不改变导航;传 false 取消本次导航,传路径或 location 对象表示重定向。

还有一条设计约束:lazy loader 不能用 reroute()。它不阻塞导航,导航早就提交了,此时改目标毫无意义。

6. 四种取数方案的取舍 ​

选型时最容易被忽略的其实是"导航该不该等数据"。等,首屏更完整但点击有延迟;不等,点击立刻响应但会闪一下空状态。

方案并行可取消缓存阻塞导航适用
onMounted 内请求❌ 依赖挂载顺序需手写需自建❌弹窗、局部刷新
beforeEach 里 await需手写 Promise.all需手写需自建✅强依赖数据的鉴权跳转
Basic Loader✅ 自动✅ 内置 signal❌ 每次导航重取✅数据实时性优先的详情页
Colada Loader✅ 自动建议不取消✅ staleTime + 去重✅列表、可回退的浏览型页面

最后一行有个反直觉的点:用 Colada Loader 时官方建议不要取消请求。它的价值来自缓存复用,中断请求等于放弃"用户返回上一页时秒开"的收益。取消策略和缓存策略必须一起决策,分开拍必然返工。

明确一条我不建议的做法:不建议在 beforeEach 里 await 取数,除非那是鉴权跳转。守卫里取数会阻塞每一次导航,包括你只是想改个 query 的场景;而且守卫拿不到 pack 的原子性,失败时页面状态是半新半旧的。

7. 三个常见误解 ​

很多人以为 Data Loader 是 <Suspense> 的替代品,实际上两者解决的不是同一层问题:Suspense 等的是组件内部的异步 setup,取数仍写在组件里、仍受挂载顺序影响;Data Loader 等的是路由级的数据准备,取数发生在组件存在之前。已经在用 Suspense 的项目迁过来,收益来自并行化与缓存解耦,不是少写几个 await。

很多人以为 loader 之间会自动做依赖分析,实际上不会。把 customerId 拆成两个 loader 依然是两次往返,正确做法是在第一个 loader 里一次取回,或者让后端出聚合接口。

很多人以为客户端跑通就等于 SSR 跑通,实际上差得远。服务端渲染有两个只在真机上暴露的约束:一是超时,客户端卡住用户还能刷新,服务端卡住会一直挂到网关超时,所以 loader 里的下游请求必须设超时,超时后抛预期错误、退化成骨架屏直出;二是状态隔离,服务端进程是复用的,任何写进模块级变量的结果都会在请求之间泄漏,取数结果只能存在请求上下文里。这两点在 vite dev 下完全不会暴露。

8. 想一想,然后动手 ​

第一题。你的详情页有四个 loader,其中一个依赖最快的那个接口的返回值才能发。把依赖的那个改成 lazy loader,首屏会变快吗?为什么?

第二题。reload() 抛出的错误会走 errors 过滤吗?如果不会,你的重试逻辑应该写在哪一层?

第三题。给一个已经用 beforeEach 做鉴权的中后台加 Data Loader,你要怎么用测试把"守卫先于 loader"这个顺序固定下来?直觉在这里不可靠。

9. 中英名词对照 ​

中文英文一句话解释
数据加载器Data Loader定义在页面组件上、由路由在导航阶段收集执行的取数函数
打包提交pack一次导航内所有 loader 结果作为一个原子单元生效或全部丢弃
预期错误expected error显式声明后不中止导航、交由页面渲染错误态的错误类型
重定向reroute在 loader 内改变导航目标,内部以抛异常实现
导航阻塞blocking navigation导航提交被推迟到数据就绪之后
延迟加载器lazy loader不阻塞导航、数据就绪后单独更新的 loader
取数瀑布流request waterfall因组件挂载顺序被强制串行的多次请求