SvelteKit 导航类型迁移:从 `@sveltejs/kit` 到 `$app/navigation` 的 breaking change 解读

原创2026-09-20 23:12:341,885 阅读
文章标签:Web框架后端前端

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, GotoOptions and the Navigation* variant types from @sveltejs/kit to $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 与类型的唯一入口,这既简化了导入路径,也降低了维护时类型漂移的风险。

升级注意事项

  1. 仅影响类型:本次变更不改变导航运行时行为,beforeNavigate 回调中调用 cancel() 取消导航、afterNavigate 在导航完成后触发等语义均保持不变;
  2. Navigation 联合类型的变化:Navigation 由 NavigationExternal(NavigationGoto | NavigationLeave)、NavigationFormSubmit、NavigationPopState、NavigationLink 组成;各变体分别携带对应事件对象(SubmitEvent、PopStateEvent、PointerEvent)与 delta 字段;
  3. 回调类型收窄:OnNavigate 与 AfterNavigate 对 type 与 willUnload 做了收窄,迁移后这部分类型约束依然有效,可帮助你在回调中安全访问 event、delta 等字段;
  4. 弃用别名:replaceState 与 invalidateAll 已标记为 deprecated,建议在本次升级中一并改用 replace 与 refreshAll。

相关文档与源码入口

以上迁移路径已在 SvelteKit 后续版本(SvelteKit 3 及更高)中落地,升级时请以你使用的 SvelteKit 版本实际导出的类型为准。

登录后查看全文
kit