Next.js 15.3 Link组件大改引发的坑:next-navigation-guard事件捕获拦截方案全解读
Next.js 15.3 Link组件大改引发的坑:next-navigation-guard事件捕获拦截方案全解读
next-navigation-guard 是一个为 Next.js 提供「导航守卫」(Navigation Guard)功能的开源库,就像 Nuxt 的 Navigation Guard 一样,让你在用户离开有未保存内容的页面前弹出确认弹窗。而 Next.js 15.3 对 Link 组件的重构直接让大量"点击拦截"方案失效,本文带你完整解读 next-navigation-guard 是如何用「事件捕获 + Router 拦截」双保险方案绕开这个坑的。
一个真实痛点:用户误点导致表单丢失
做过中后台或表单页的前端都知道这个噩梦场景:
- 用户在页面上填了 10 分钟的表单
- 手滑点了一个导航链接
- 页面直接跳走,数据全部丢失 😱
传统 SPA 框架(如 Vue/Nuxt)都自带 beforeRouteLeave 之类的导航守卫,但 Next.js 一直没有官方方案。next-navigation-guard 就是为这个缺口而生的。
坑从何来:Next.js 15.3 Link组件大改
在 Next.js 15.3 之前,<Link> 组件内部调用的是 router.push()。因此很多导航守卫库(包括早期的 next-navigation-guard)采用的策略是:替换 React Context 中的 router 对象,在 push/replace 方法上加一层守卫 —— 拦截点清晰可靠。
但 15.3 起,Link 组件不再走 router.push(),而是通过更底层的导航机制直接完成跳转。结果就是:
- ❌ 点击
<Link>时,被拦截的 router 方法根本不会被调用 - ❌ 原有"Context 替换"方案对链接点击完全失灵
- ❌ 只有编程式调用
useRouter().push()时才能被拦到
这也是 CHANGELOG 中 v0.2.0 版本明确记录的重点更新:
Support for Next.js 15.3+ Link component which no longer uses router.push()
双保险方案一:事件捕获拦截 Link 点击
为应对 15.3+ 的新行为,next-navigation-guard 增加了一个关键的"兜底"机制 —— 在全局用捕获阶段(capture phase)监听 click 事件,核心实现在 src/hooks/useInterceptLinkClicks.ts:
// 在捕获阶段添加监听器,抢在 React 之前拦截
document.addEventListener('click', handleLinkClick, true)
这个监听器的工作流程非常讲究,可以归纳为 4 步:
| 步骤 | 逻辑 | 目的 |
|---|---|---|
| 1. 找到链接 | e.target.closest('a[href]') |
命中真实的 <a> 元素 |
| 2. 过滤噪音 | 跳过外链、# 锚点、target="_blank"、download、Ctrl/Cmd 修饰键、鼠标中键 |
只拦截站内常规点击 |
| 3. 执行守卫 | 依次调用所有启用的 guard 回调(支持异步) | 弹出确认弹窗 |
| 4. 放行或拦截 | 通过则 preventDefault() 后用 router.push/replace 编程式跳转;不通过则终止 |
精确控制导航 |
几个值得注意的细节:
- 捕获阶段优先:
addEventListener第三个参数为true,确保比 React 的合成事件更早介入,这是能拦截 15.3+ 新Link的关键 - 防重入标记:用
dataset.guardProcessing防止同一次点击被处理两次 - 尊重用户意图:中键点击、Ctrl/Cmd 点击(新标签页打开)、锚点跳转一律放行,不干扰正常浏览习惯
- MutationObserver 兜底:监控 DOM 动态插入的新链接,保证 SPA 场景下新增的导航元素同样受保护
双保险方案二:替换 Router Context 拦截编程式导航
事件捕获只能拦住"点击",但代码里调用 router.push()、router.replace()、router.refresh() 依然要拦。这部分沿用经典的 Context 替换技巧:
- App Router:src/components/InterceptAppRouterProvider.tsx 读取原始
AppRouterContext,在 src/hooks/useInterceptedAppRouter.ts 中生成一个"守卫版" router 重新注入 Context,包装了push、replace、refresh三个方法 - Pages Router:src/components/InterceptPagesRouterProvider.tsx 对
RouterContext做同样处理,对应逻辑在 src/hooks/useInterceptedPagesRouter.ts
两套 Provider 会同时挂载(见 src/components/NavigationGuardProvider.tsx),不在对应路由模式下就自动透传,互不干扰。
别忘了浏览器原生行为:后退按钮和关闭页签
导航守卫的完整覆盖还包括两条"非 React"通道:
1. 后退/前进按钮(popstate)
难点在于:popstate 无法真正"阻止",只能拦截后"回滚"。next-navigation-guard 的做法相当巧妙(实现见 src/hooks/useInterceptPopState.ts):
- 借助 src/utils/historyAugmentation.tsx 给
history.pushState/replaceState打补丁,在每条历史记录里写入栈序号 + 随机 token - 收到
popstate后比较 token 和序号差值delta,先挂起事件并向用户确认 - 用户拒绝时执行
history.go(-delta)把地址栏"弹回"原位置,视觉上如同什么都没发生;用户同意则手动重放一次 popstate 让 Next.js 正常响应
2. 关闭页签/刷新(beforeunload)
实现位于 src/hooks/useInterceptPageUnload.ts,只要任一守卫处于启用状态就 preventDefault() 触发浏览器原生的"离开确认"。注意此通道只能同步判断,无法等待异步弹窗结果,这也是浏览器的安全限制。
5分钟上手指南
第一步:安装
npm install next-navigation-guard
支持 Next.js 14 / 15 / 16 与 React 18 / 19(见 package.json 中的 peerDependencies)。
第二步:挂载 Provider
- App Router 写在
app/layout.tsx的<body>内 - Pages Router 写在
pages/_app.tsx中包裹<Component />
第三步:注册守卫
最简写法(原生确认框):
useNavigationGuard({
enabled: form.changed,
confirm: () => window.confirm("You have unsaved changes that will be lost.")
})
如果想要自定义弹窗组件,就不传 confirm,而是使用 hook 返回的 active / accept / reject 三个成员,完整可运行示例见 example/src/components/NavigationGuardToggle.tsx。
enabled 还可以是一个函数,接收 { to, type } 参数按目标路由和导航类型(push / replace / refresh / popstate / beforeunload,定义见 src/types.ts)动态决定是否启用守卫。
避坑清单:常见 FAQ
- 测试环境报 "must be used within a NavigationGuardProvider"? 单元测试或 Storybook 中传入
disableForTesting: true即可让 hook 变成完全的空操作(v0.3.0 新增,见 src/hooks/useNavigationGuard.ts) - 为什么
beforeunload里不能用自定义弹窗? 浏览器无法等待异步结果,自定义弹窗只适用于站内导航场景 - 老版本 Next.js 能用事件捕获方案吗? 可以,监听器会自动检测是否处于 App Router 环境,旧版本下自动跳过(src/hooks/useInterceptLinkClicks.ts)
- 回归测试怎么做的? 项目内置了 Playwright E2E 套件,对 App Router 和 Pages Router 各跑一遍完整场景,见 e2e/navigation-guard.spec.ts 与 playwright.config.ts
项目结构速览
| 目录 | 作用 |
|---|---|
| src/components/ | 各路由模式的拦截 Provider 与 Provider 上下文 |
| src/hooks/ | 事件捕获、popstate、beforeunload、router 拦截等核心逻辑 |
| src/utils/historyAugmentation.tsx | history 栈状态注入,支撑后退拦截 |
| example/ | App Router + Pages Router 双模式可运行示例 |
| e2e/ | Playwright 端到端测试 |
总结
Next.js 15.3 的 Link 组件重构给导航守卫类方案出了一道难题,而 next-navigation-guard 的解法很典型:Router Context 拦截负责编程式导航,捕获阶段 click 事件拦截负责 15.3+ 的链接点击,popstate 回滚 + beforeunload 补全浏览器原生通道,三条防线拼成完整的"离开拦截网"。如果你正在被"未保存变更丢失"问题困扰,这套事件捕获拦截方案值得直接借鉴。