后退按钮怎么也拦不住?揭秘next-navigation-guard的popstate拦截与回滚黑魔法

原创2026-11-19 10:00:035 阅读

后退按钮怎么也拦不住?揭秘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,三步接入,一劳永逸。

登录后查看全文
next-navigation-guard