如何在Next.js App Router项目中监听popstate事件

方法1：使用官方API beforeNavigate（推荐） #

Next.js 13.4及以上版本提供了beforeNavigate函数，专门用于拦截客户端导航，包括浏览器回退/前进操作，可完全替代Pages Router中的beforePopState方法。

在客户端组件中使用示例：

'use client';

import { beforeNavigate } from 'next/navigation';
import { useEffect } from 'react';

export default function NavigationGuard() {
  useEffect(() => {
    const cleanup = beforeNavigate(({ type }) => {
      // 匹配浏览器回退/前进触发的导航（对应POP类型）
      if (type === 'POP') {
        const confirmLeave = window.confirm('确定要离开当前页面吗？');
        if (!confirmLeave) {
          // 返回false阻止导航
          return false;
        }
      }
    });

    return cleanup;
  }, []);

  return null;
}

将这个组件添加到根布局（app/layout.tsx）中，即可实现全局的回退拦截。当用户点击浏览器回退/前进按钮时，会触发确认弹窗，若用户取消则阻止导航。

方法2：结合usePathname与popstate事件（兼容旧版本） #

如果你的Next.js版本低于13.4，可以通过跟踪路径变化+监听popstate事件实现拦截：

'use client';

import { usePathname } from 'next/navigation';
import { useEffect, useState } from 'react';

export default function NavigationGuard() {
  const currentPath = usePathname();
  const [prevPath, setPrevPath] = useState(currentPath);

  useEffect(() => {
    const handlePopState = () => {
      const confirmLeave = window.confirm('确定要回退吗？');
      if (!confirmLeave) {
        // 恢复之前的路径，抵消浏览器回退操作
        window.history.pushState(null, '', prevPath);
        setPrevPath(currentPath);
      } else {
        setPrevPath(currentPath);
      }
    };

    window.addEventListener('popstate', handlePopState);

    // 监听路径变化，更新历史路径记录
    const pathObserver = new MutationObserver(() => {
      setPrevPath(currentPath);
    });
    pathObserver.observe(document.body, { subtree: true, childList: true });

    return () => {
      window.removeEventListener('popstate', handlePopState);
      pathObserver.disconnect();
    };
  }, [currentPath]);

  return null;
}

通过usePathname获取当前路由，用MutationObserver监听路由变化以更新历史路径记录；当popstate事件触发时，弹出确认框，根据用户选择决定是否阻止回退。

关键提示 #

• 所有拦截逻辑必须放在客户端组件中（添加'use client'指令），因为涉及浏览器API与客户端导航钩子。
• 优先使用beforeNavigate方案，这是官方为App Router设计的导航拦截API，稳定性更高。
• 不要直接依赖原生window.popstate事件，Next.js App Router会内部处理该事件，导致自定义监听无法可靠触发。

内容的提问来源于stack exchange，提问作者hayata_suenaga