在 SvelteKit 应用开发里，当用户处于数据录入或编辑状态时，如果不小心点击了站内链接、返回按钮或者执行了编程式跳转，很容易造成未保存内容丢失。为了避免这类误操作，我们可以利用框架内置的导航生命周期函数，在路由真正发生变化之前插入确认逻辑，让用户自行决定是否离开当前页面。
理解 beforeNavigate 的工作机制
SvelteKit 从 @sveltejs/kit 中导出了 beforeNavigate 函数，它接收一个回调函数作为参数。每当应用即将通过客户端路由跳转到其他页面时，该回调就会被执行。回调参数是一个导航对象，包含 from、to、type 以及 cancel 方法等关键信息。
如果回调函数返回 false，或者直接调用了导航对象的 cancel() 方法，那么本次跳转就会被中止。这种机制不同于服务端中间件，它完全运行在浏览器端，专门用于改善交互体验。值得注意的是，beforeNavigate 只对 SvelteKit 管理的客户端导航生效，像用户手动输入新网址、刷新页面或关闭浏览器标签等行为并不受它控制。
在布局中全局添加确认提示
若希望在整个站点范围内，只要存在未保存数据就提示用户，可以把逻辑放在根布局文件 +layout.svelte 里。这样所有子页面都能继承这一行为，不必重复编写代码。
下面的示例展示了如何在布局中注册一个全局导航守卫，通过共享的 Store 来判断当前是否有未保存的表单内容：
import { beforeNavigate } from '@sveltejs/kit';
import { writable } from 'svelte/store';
// 一个全局可写的 Store，标记页面是否存在未保存改动
export const dirty = writable(false);
beforeNavigate((navigation) => {
if (dirty && !navigation.willUnload) {
const confirmLeave = window.confirm('当前页面有未保存的内容，确定要离开吗？');
if (!confirmLeave) {
navigation.cancel();
}
}
});
在上面的代码中，我们先从 Kit 中引入 beforeNavigate，并创建一个名为 dirty 的 Store。当 dirty 为 true 且本次导航不是浏览器卸载时，就弹出原生确认框。若用户选择取消，则调用 navigation.cancel() 阻止跳转。
这种写法的优势在于集中管理，任何页面只需修改 dirty 的值即可参与保护。缺点是缺乏灵活性，无法针对特定路由做差异化处理，而且 window.confirm 的样式不可定制，在追求体验一致性的项目中可能显得突兀。
在单个页面内局部使用
很多时候我们只需要在特定编辑页开启确认，这时可以把 beforeNavigate 直接写在对应页面的 +page.svelte 的 script 块中。由于 Svelte 组件卸载时会自动清理通过该函数注册的回调，因此不必担心内存泄漏或影响其他页面。
以下代码演示了一个本地表单页面的典型用法，结合 Svelte 的响应式变量来控制提示：
<script>
import { beforeNavigate } from '@sveltejs/kit';
let formDirty = false;
function handleInput() {
formDirty = true;
}
beforeNavigate((navigation) => {
if (formDirty) {
const ok = window.confirm('您填写的表单尚未提交，离开将丢失数据');
if (!ok) {
navigation.cancel();
}
}
});
</script>
<form>
<textarea on:input={handleInput} placeholder="请输入内容"></textarea>
<button type="submit">保存</button>
</form>
这里我们在 handleInput 中将 formDirty 置为 true，表示用户已经修改过内容。beforeNavigate 回调检查该变量，若有改动就弹窗询问。用户确认离开后，formDirty 可随组件销毁自然重置。
局部方式的优点是不会干扰无关页面，逻辑内聚、易于维护。但如果项目中有大量类似页面，仍建议抽取成可复用的 Action 或函数，减少重复代码。
使用自定义弹窗替代原生确认框
原生 window.confirm 虽然简单，但UI风格老旧且会阻塞线程。在现代化前端项目中，我们往往用 Svelte 组件自己实现一个异步确认弹窗，再配合 Promise 来控制导航。
由于 beforeNavigate 的回调支持返回 Promise，我们可以等待用户点击自定义弹窗的按钮后再决定放行与否。示例结构如下：
import { beforeNavigate } from '@sveltejs/kit';
import { showConfirm } from '$lib/confirmDialog';
beforeNavigate(async (navigation) => {
if (hasUnsavedChanges) {
const result = await showConfirm({
title: '提示',
message: '有未保存的修改，确定离开？'
});
if (!result) {
navigation.cancel();
}
}
});
上述 showConfirm 是一个返回 Promise 的弹窗工具，用户点击确定时 resolve true，取消时 resolve false。通过 async/await，我们能让守卫逻辑看起来像同步代码一样直观。
采用自定义弹窗的好处是视觉统一、可展示更丰富的文案，也方便接入国际化。代价是需要额外开发弹窗组件，并且要处理好弹窗自身的 z-index 与焦点陷阱，避免无障碍访问问题。
常见误区与注意事项
不少初学者会误以为 beforeNavigate 能拦截所有离开行为，实际上它无法阻止浏览器刷新或关闭。若需要覆盖这类场景，应配合 window.onbeforeunload 事件做补充。另外，在 SSR 阶段该函数不会执行，因此相关逻辑必须放在浏览器端才生效。
还有一点容易忽略：如果在回调中既返回了 false 又调用了 cancel()，虽然都能中止导航，但混用可能造成阅读困惑。推荐统一采用返回布尔值或统一调用 cancel() 其中一种风格，保持团队代码一致。
| 方案 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| 全局布局守卫 | 全站表单保护 | 集中管理，少重复 | 不够灵活 |
| 页面局部守卫 | 单一编辑页 | 逻辑内聚 | 多页面需复用 |
| 自定义弹窗 | 体验要求高 | UI统一 | 开发量大 |
综合来看，SvelteKit 的 beforeNavigate 为路由跳转前确认提供了轻量且原生的支持。开发者只需根据项目规模选择合适的封装层级，就能在不引入额外依赖的情况下，稳妥地规避误操作带来的数据损失风险。
SvelteKit路由守卫beforeNavigate修改时间：2026-07-31 16:12:38