SvelteKit 导航类型迁移:从 `@sveltejs/kit` 到 `$app/navigation` 的 breaking change 解读
SvelteKit 导航类型迁移:从 @sveltejs/kit 到 $app/navigation 的 breaking change 解读
本篇指南聚焦 SvelteKit 一次重要的破坏性变更(breaking change):将 BeforeNavigate、OnNavigate、AfterNavigate、Navigation、NavigationTarget、NavigationType、GotoOptions 以及全部 Navigation* 变体类型从 @sveltejs/kit 迁移至 $app/navigation 模块。文章将说明该变更的动机、影响范围、迁移方法与底层实现证据,帮助你快速完成依赖升级与类型导入修正。
变更概述
在 SvelteKit 的版本规划中,.changeset/pre/tidy-waves.md 记录了一次标记为 major(破坏性)的变更:
breaking: move
BeforeNavigate,OnNavigate,AfterNavigate,Navigation,NavigationTarget,NavigationType,GotoOptionsand theNavigation*variant types from@sveltejs/kitto$app/navigation
这意味着:
- 旧写法:从
@sveltejs/kit导入上述导航相关类型; - 新写法:必须改为从
$app/navigation导入。
变更仅涉及类型(type-level),不改变运行时 API 行为,但由于 @sveltejs/kit 不再导出这些类型,TypeScript 编译将直接报错,属于必须跟随升级的破坏性变更。
为什么迁移到 $app/navigation
从源码结构看,这一变更的核心动机是让导航类型与其运行时 API 保持同源。
- 导航相关的运行时函数(
beforeNavigate、afterNavigate、onNavigate、goto、invalidate等)一直由 runtime/app/navigation 提供,其公开类型声明位于 public.d.ts; - 而对应的导航类型此前却从
@sveltejs/kit的 public.d.ts 导出,类型与运行时 API 分居两处,导致用户需要同时从两个模块导入相关符号。
迁移后,导航类型与其运行时函数统一归入 $app/navigation,开发者只需从一个模块导入,类型查找与自动补全体验更加一致。
受影响类型清单
本次变更涉及的完整类型清单如下(均可在 packages/kit/src/runtime/app/navigation/public.d.ts 中找到定义):
| 类型 | 说明 |
|---|---|
Navigation |
导航联合类型,涵盖 NavigationExternal、NavigationFormSubmit、NavigationPopState、NavigationLink |
NavigationTarget |
导航目标信息(params、route、url、scroll) |
NavigationType |
导航类型字面量:'enter' | 'form' | 'leave' | 'link' | 'goto' | 'popstate' |
BeforeNavigate |
Navigation & { cancel: () => void },用于 beforeNavigate 回调 |
OnNavigate |
排除了 'enter' | 'leave' 的导航,willUnload 恒为 false |
AfterNavigate |
排除了 'leave' 的导航,willUnload 恒为 false |
GotoOptions |
goto() 的选项对象(replace、shallow、reset 等) |
NavigationEnter / NavigationGoto / NavigationLeave / NavigationFormSubmit / NavigationPopState / NavigationLink |
各具体导航变体类型 |
各类型的核心字段
在 public.d.ts 中,导航事件对象统一基于 NavigationBase 构建,包含以下字段:
type:导航类型(见上表NavigationType);shallow:是否为浅导航(shallow navigation);from/to:NavigationTarget,分别表示导航起点与目标(可能为null);willUnload:导航是否会导致页面卸载(即非客户端导航);complete:一个在导航完成时 resolve、失败或中止时 reject 的 Promise(willUnload场景下永不 resolve)。
NavigationTarget 则描述导航目标:
params:目标路由参数,例如/blog/[slug]对应{ slug: string };若目标无法解析为应用内路由则为null;route.id:目标路由 ID,例如src/routes/blog/[slug]对应/blog/[slug],无匹配时返回null;url:导航目标 URL;scroll:导航关联的滚动位置。对from而言是导航发生瞬间的滚动位置;对to而言,在beforeNavigate与onNavigate中仅popstate导航可用,在afterNavigate中则是导航完成后实际应用的滚动位置。
GotoOptions 支持以下选项:
replace:为true时替换当前历史记录项而非新建(默认false;replaceState已弃用,请改用replace);shallow:为true时仅更新 URL 与page.state,不触发导航(默认false);reset:为true时在导航完成后重置滚动位置与焦点(默认true;shallow为true时默认false);refreshAll:为true时重新运行页面所有load函数与查询(默认false;invalidateAll已弃用,请改用refreshAll);invalidate:重新运行依赖这些 URL 的load函数;state:作为page.state可用的对象;persistState:为true时,全量页面刷新后恢复page.state(默认false)。
迁移步骤
1. 更新类型导入
将原先从 @sveltejs/kit 导入的导航类型改为从 $app/navigation 导入:
// 旧写法(升级后将报错)
import type { BeforeNavigate, GotoOptions } from '@sveltejs/kit';
// 新写法
import type { BeforeNavigate, GotoOptions } from '$app/navigation';
运行时函数(goto、beforeNavigate、afterNavigate、onNavigate 等)的导入方式不变,它们本就从 $app/navigation 导出:
import { goto, beforeNavigate, afterNavigate, onNavigate } from '$app/navigation';
2. 检查自定义类型与泛型约束
若你的代码中存在基于这些类型的自定义封装或回调签名,请同步调整:
// 旧写法
import type { NavigationTarget } from '@sveltejs/kit';
export function track(to: NavigationTarget | null) { /* ... */ }
// 新写法
import type { NavigationTarget } from '$app/navigation';
export function track(to: NavigationTarget | null) { /* ... */ }
3. 验证编译与类型检查
升级后运行项目的类型检查(如 svelte-check 或 tsc)确认无类型错误;若仍从 @sveltejs/kit 引用这些类型,编译器会提示模块中不存在对应导出。
源码层面对比验证
在仓库源码中,可以清晰地看到这次迁移的前后差异:
- 迁移目标(新):packages/kit/src/runtime/app/navigation/public.d.ts 完整定义了
NavigationTarget、GotoOptions、NavigationType、NavigationBase及全部Navigation*变体、BeforeNavigate、OnNavigate、AfterNavigate; - 运行时消费方(新):packages/kit/src/runtime/client/client.js 在实现中直接以
import type { AfterNavigate, BeforeNavigate, GotoOptions, Navigation, NavigationTarget, NavigationType, OnNavigate } from '$app/navigation'引用这些类型,说明运行时与类型已统一归口到同一模块; - 导出枢纽:packages/kit/src/runtime/app/navigation/index.js 通过
export * from '#app/navigation'将运行时 API 与类型一并对外暴露。
从代码组织可以推断,迁移完成后 @sveltejs/kit 将不再承担导航类型的导出职责,$app/navigation 成为导航相关 API 与类型的唯一入口,这既简化了导入路径,也降低了维护时类型漂移的风险。
升级注意事项
- 仅影响类型:本次变更不改变导航运行时行为,
beforeNavigate回调中调用cancel()取消导航、afterNavigate在导航完成后触发等语义均保持不变; Navigation联合类型的变化:Navigation由NavigationExternal(NavigationGoto | NavigationLeave)、NavigationFormSubmit、NavigationPopState、NavigationLink组成;各变体分别携带对应事件对象(SubmitEvent、PopStateEvent、PointerEvent)与delta字段;- 回调类型收窄:
OnNavigate与AfterNavigate对type与willUnload做了收窄,迁移后这部分类型约束依然有效,可帮助你在回调中安全访问event、delta等字段; - 弃用别名:
replaceState与invalidateAll已标记为 deprecated,建议在本次升级中一并改用replace与refreshAll。
相关文档与源码入口
- 变更声明:.changeset/pre/tidy-waves.md
- 导航类型定义:packages/kit/src/runtime/app/navigation/public.d.ts
- 运行时实现(类型消费方):packages/kit/src/runtime/client/client.js
- 模块导出枢纽:packages/kit/src/runtime/app/navigation/index.js
- 官方导航指南:documentation/docs/20-core-concepts/10-routing.md
- 模块参考文档:documentation/docs/98-reference/20-$app-navigation.md
以上迁移路径已在 SvelteKit 后续版本(SvelteKit 3 及更高)中落地,升级时请以你使用的 SvelteKit 版本实际导出的类型为准。