后退按钮怎么也拦不住?揭秘next-navigation-guard的popstate拦截与回滚黑魔法
后退按钮怎么也拦不住?揭秘next-navigation-guard的popstate拦截与回滚黑魔法
next-navigation-guard 是一个为 Next.js 打造的导航守卫(Navigation Guard)库,像 Nuxt 的 Navigation Guard 一样,让你在用户点击浏览器后退按钮、前进按钮或关闭页面时弹出"您有未保存的更改"确认框。本文将揭秘它如何用 popstate 拦截和 history 回滚这两个"黑魔法",把浏览器中最难拦截的后退按钮牢牢抓住。
一、为什么后退按钮这么难拦?
大多数导航拦截都很简单:router.push() 是你自己代码里调用的,只要包一层 if (confirm(...)) 就能拦住。
但浏览器后退按钮不一样。用户按下后退时,是浏览器本身触发了 history 指针的移动,随后派发 popstate 事件——你的 JavaScript 只能监听这个事件,却无法取消它。等你的代码执行到 confirm 时,URL 地址栏可能已经变了,Next.js 的 router 也已经收到通知准备切换页面了。
这就像高速公路上的紧急出口:你可以放路障(拦截点击),但开闸放行的权力在司机(浏览器)手里。
next-navigation-guard 的答案是:不拦水,改河道。 它让"已发生的后退"变成"可撤销的后退"。
二、第一步:抢先一步监听 popstate
在 src/hooks/useInterceptPopState.ts 中,整个拦截动作被放在 useLayoutEffect 中执行——这是一个刻意的设计:
Next.js 的 router 是在
useEffect中完成 setup 的,而useLayoutEffect会在它之前运行。
这意味着 next-navigation-guard 的 popstate 监听器总是比 Next.js 的监听器先注册。监听顺序在 DOM 事件系统中是"先到先得"——先注册先执行,谁先喊"停止传播",后面的人就收不到事件。
三、第二步:给历史栈"打标"——回滚魔法的基石
拦截本身还不够。真正的难题是:用户按下后退,URL 已经变了,如果他在确认框点了"取消",如何把 URL 变回去?
答案藏在 src/utils/historyAugmentation.tsx 里。库启动时会包裹(monkey patch)history.pushState 和 history.replaceState,在每一次写入 history 时偷偷塞进两个自定义字段:
__next_navigation_guard_token // 一串随机令牌
__next_navigation_guard_stack_index // 历史栈序号,每 push 一次 +1
效果就像给历史栈的每一层楼都挂上门牌号:
| 历史条目 | 页面 | stack_index | token |
|---|---|---|---|
| 第 1 层 | /page1 | 0 | abc123 |
| 第 2 层 | /page2 | 1 | abc123 |
| 第 3 层 | /page3 | 2 | abc123 |
有了门牌号,任何一次 popstate 事件都能精确算出:用户想从第几层去第几层,差值 delta 就是需要回滚的步数。
而 token 的作用则是防"串号":如果用户刷新页面或从外部链接直接进入,新旧历史栈的编号可能冲突,token 不一致时直接重置基准,避免误判。
四、第三步:挂起 → 询问 → 回滚或放行
理解了打标,createHandlePopState 的主流程就清晰了,它只有三种结局:
1️⃣ 放行——没有任何守卫启用(或守卫说"去吧"):事件照常流转,Next.js 正常导航。
2️⃣ 回滚(本文的标题党主角)——守卫说"别走":
// 用户点了"取消",把历史指针推回原位
window.history.go(-delta)
用户按下后退时,URL 确实一闪变成了上一页;但确认框弹出、用户点"取消"后,go(-delta) 把指针推回原点。地址栏恢复原样,页面纹丝不动,且用户可以再次按下后退——因为历史栈本身完好无损。这就是"回滚黑魔法"的全部秘密:不是阻止后退,而是把后退当成可撤销的事务。
3️⃣ 重新派发——守卫说"去吧":库会手动重新派发一个 popstate 事件让 Next.js 完成导航,并用 dispatchedState 标记它,防止这个"二进宫"的事件被自己再次拦截死循环。
五、App Router 与 Pages Router:两套拦截姿势
由于两套路由器的内部实现不同,拦截方式也有所区别(见 useInterceptPopState.ts 中的分支逻辑):
| 维度 | App Router | Pages Router |
|---|---|---|
| 拦截手段 | popstate 监听 + stopImmediatePropagation() |
官方 router.beforePopState() API |
| 能否取消 | 阻止 Next.js 监听器收到事件 | 回调返回 false 即取消 |
| 备注 | 注释指出 Chrome 中 capture 阶段对 popstate 不生效,故用普通监听 | beforePopState 是 Next.js 官方预留的挂起点 |
两种姿势殊途同归:先于 Next.js 拿到事件,把决定权握在自己手里。
六、快速上手:3 步启用导航守卫
🚀 接入只需三步(参考 README.md):
1. 安装
pnpm install next-navigation-guard
2. 在布局中包裹 Provider(App Router 的 app/layout.tsx)
<NavigationGuardProvider>{children}</NavigationGuardProvider>
3. 在页面里注册守卫(两种风格任选)
同步确认框(最简单):
useNavigationGuard({
enabled: form.changed,
confirm: () => window.confirm("有未保存的更改,确定离开吗?")
})
自定义异步弹窗(用 active / accept / reject 控制,见 useNavigationGuard.ts):
const navGuard = useNavigationGuard({ enabled: form.changed })
// navGuard.active 为 true 时渲染你的 Dialog
// 点"离开"调 navGuard.accept(),点"取消"调 navGuard.reject()
仓库里还有一个可直接运行的示例:example/src/components/NavigationGuardToggle.tsx,切换开关即可体验同步/异步两种确认模式。
七、一张图看懂:五大拦截通道全覆盖
很多人不知道,守卫其实覆盖了五条离开页面的路径,全部挂在 NavigationGuardProvider 上:
| 拦截通道 | 实现文件 | 触发场景 |
|---|---|---|
| 🧭 popstate(后退/前进) | src/hooks/useInterceptPopState.ts | 浏览器后退/前进按钮、history.go() |
| 🔗 链接点击 | src/hooks/useInterceptLinkClicks.ts | 直接点击 <a> 标签(App Router 15.3+ 不经过 router) |
| 📦 router.push / replace / refresh | src/hooks/useInterceptedAppRouter.ts / useInterceptedPagesRouter.ts | 编程式导航 |
| 🔄 页面刷新 | 同上(refresh 类型) |
F5 / router.refresh() |
| 🚪 关闭标签页 | src/hooks/useInterceptPageUnload.ts | beforeunload 原生事件(仅同步生效) |
每条通道的守卫回调都会收到 type 参数("popstate" | "push" | "replace" | "refresh" | "beforeunload",定义见 src/types.ts),你可以按场景精细控制。
八、怎么验证?看看 Playwright 的 e2e 用例
项目用 Playwright 写了一整套回归测试 e2e/navigation-guard.spec.ts,对 App Router 和 Pages Router 双路由分别验证:
page.goBack()被拦截后停留在原页面(第 202 行)goForward()、router.back()、router.forward()、页面刷新、跳转外部链接均被守卫覆盖- 用户点"确定"时导航放行,点"取消"时页面保持不动
这套用例正是对"回滚魔法"的端到端检验:回退必须回到原点且可再次触发。
写在最后
next-navigation-guard 的精髓可以用一句话概括:既然浏览器不给你取消 popstate 的权力,那就在 history 上装一个"倒车挡"。 用 token + stack_index 给历史栈打标,用 go(-delta) 实现无感回滚,再用 stopImmediatePropagation 或 beforePopState 抢先夺权——三层配合,把 Nuxt 用户习以为常的导航守卫体验,原封不动搬进了 Next.js 的世界。
下次再遇到"后退按钮拦不住"的抓头发时刻,不妨直接 pnpm install next-navigation-guard,三步接入,一劳永逸。