
在 Next.js 13.4(App Router)中,beforeunload 事件无法触发 window.confirm(),但可通过标准浏览器原生提示实现跳转拦截;需正确设置 event.returnValue 并返回字符串,且仅对导航类操作(如刷新、关闭、地址栏输入)生效,不适用于客户端路由跳转(如 Link 或 router.push)。
在 next.js 13.4(app router)中,阻止用户意外离开页面并确认 url 跳转需谨慎处理:`beforeunload` 事件**不支持自定义弹窗(如 `window.confirm()`)**,浏览器会忽略其调用并静默使用内置提示;正确做法是仅设置 `event.returnvalue` 为非空字符串,并返回该值,从而触发标准的“离开此页面?”原生警告。
Next.js 13.4 默认使用 App Router,其客户端导航(如 、useRouter().push())完全由 React 和 Next 内部路由系统接管,不会触发 beforeunload 事件。因此,beforeunload 仅对以下行为有效:
- 浏览器刷新(F5 / Cmd+R)
- 关闭标签页/窗口
- 直接在地址栏修改 URL 并回车
- 点击非 Next 路由的外部链接(如
@#@#@#@#@#@#@#@#@#@0)
✅ 正确实现方式(推荐在 useEffect 中注册):
'use client';
import { useEffect } from 'react';
export default function PreventUnsavedExit() {
useEffect(() => {
const handleBeforeUnload = (event: BeforeUnloadEvent) => {
// ✅ 判断是否有未保存更改(根据你的业务逻辑)
const hasUnsavedChanges = true; // 替换为实际状态,如 useFormState 或 ref
if (hasUnsavedChanges) {
// ⚠️ 必须设置 returnValue(现代浏览器要求)
event.returnValue = 'You have unsaved changes. Are you sure you want to leave?';
// ⚠️ 必须显式返回相同字符串(兼容旧版浏览器)
return event.returnValue;
}
};
window.addEventListener('beforeunload', handleBeforeUnload);
return () => {
window.removeEventListener('beforeunload', handleBeforeUnload);
};
}, []);
return null; // 此组件仅用于副作用,无需渲染内容
}
? 重要注意事项:
一个基于官方 Mailtrap Node.js SDK 构建的 ASE 技能,用于发送事务邮件并与 Mailtrap 沙盒或生产流程协作。它非常适合需要 API 驱动邮件投递、测试邮箱验证和结构化消息自动化的代理工作流。
- ❌ 不要调用
window.confirm()、alert()或任何同步阻塞方法——它们在beforeunload中被浏览器禁用,且会导致控制台报错或静默失败; - ✅
event.returnValue必须是非空字符串(如' '也有效),空字符串或undefined将使提示失效; - ? 对于 Next.js 客户端路由跳转(如
router.push('/about')),beforeunload完全不触发。此时应改用router.events.on('routeChangeStart', ...)配合自定义确认逻辑(需手动拦截 +e.preventDefault()+ 弹窗 + 条件性跳转); - ? 若需统一拦截所有退出场景(含客户端导航),建议封装一个可复用的
usePreventRouteChangeHook:
import { useEffect } from 'react';
import { useRouter } from 'next/navigation';
export function usePreventRouteChange(
shouldBlock: boolean,
message = 'You have unsaved changes. Are you sure you want to leave?'
) {
const router = useRouter();
useEffect(() => {
const handleBeforeUnload = (event: BeforeUnloadEvent) => {
if (shouldBlock) {
event.returnValue = message;
return message;
}
};
const handleRouteChangeStart = (url: string) => {
if (shouldBlock && !confirm(message)) {
// 注意:此处无法真正“取消”已开始的跳转,仅作提醒
// 更健壮方案:结合状态管理 + 受控导航(如点击按钮时先 confirm 再 push)
throw new Error('Navigation blocked by user confirmation');
}
};
window.addEventListener('beforeunload', handleBeforeUnload);
router.events.on('routeChangeStart', handleRouteChangeStart);
return () => {
window.removeEventListener('beforeunload', handleBeforeUnload);
router.events.off('routeChangeStart', handleRouteChangeStart);
};
}, [shouldBlock, message, router]);
}
? 总结:beforeunload 是浏览器级防护,轻量但能力有限;它不能替代应用层的导航控制。真实项目中,应优先在用户交互点(如提交按钮、离开按钮)主动调用 confirm() 并条件执行跳转,再辅以 beforeunload 作为兜底防护。两者结合,才能兼顾体验与可靠性。










