本文详解如何在 React 应用中正确拦截页面刷新（beforeunload），避免 Socket.IO 连接在用户未确认前被强制断开，并确保「确认弹窗→Socket 通知→路由跳转」流程可控、同步、无竞态。
本文详解如何在 react 应用中正确拦截页面刷新（`beforeunload`），避免 socket.io 连接在用户未确认前被强制断开，并确保「确认弹窗→socket 通知→路由跳转」流程可控、同步、无竞态。
在 React 单页应用中集成实时通信（如 Socket.IO）时，一个常见但易被忽视的问题是：用户点击浏览器刷新按钮后，系统会立即触发 beforeunload 事件并开始卸载流程，而此时异步的 Socket 断连逻辑（如 socket.emit("leave_room", room)）根本来不及执行，导致服务端残留无效连接、房间状态异常或主机切换失败。
根本原因在于：
✅ beforeunload 是同步阻塞事件，仅支持返回字符串以触发浏览器原生确认对话框；
❌ 它不等待任何异步操作完成（如 socket.emit、fetch 或 setTimeout）；
❌ 浏览器一旦收到 event.returnValue，就会在用户点击「离开」后立即销毁页面上下文——此时 React 组件已卸载，socket 实例可能失效，回调无法执行。
因此，试图在 beforeunload 回调中直接调用异步 Socket 方法（或依赖 useEffect 清理函数）注定失败。正确解法是：将“用户意图”与“实际清理动作”解耦——用 beforeunload 控制是否弹窗，用 unload 或显式断连逻辑处理副作用。
✅ 推荐实现方案（稳定、符合规范）
以下代码基于 React Router v6+ 和 Socket.IO Client v4+，关键改进点：
- 仅在 beforeunload 中设置提示文本，不执行任何副作用；
- 利用 socket.disconnect() 的可靠性 + 自定义事件监听，确保断连逻辑在页面卸载前完成；
- 使用 shouldPrompt 状态精准控制提示时机，避免重复触发；
- 移除不可靠的 popstate + window.confirm 组合（该方式在刷新时根本不会触发 popstate）。
import React, { useState, useEffect, useCallback } from 'react';
import { useNavigate, useLocation } from 'react-router-dom';
import io from 'socket.io-client';
// 假设 socket 已全局初始化或通过 context 注入
const socket = io('http://localhost:3001');
function Game() {
const navigate = useNavigate();
const location = useLocation();
const [shouldPrompt, setShouldPrompt] = useState(true);
// ? 核心：仅在 beforeunload 中设置提示，不执行异步操作
const handleBeforeUnload = useCallback((event: BeforeUnloadEvent) => {
if (shouldPrompt) {
event.preventDefault();
event.returnValue = '您有未保存的游戏操作，确定要离开吗？'; // 返回字符串即触发浏览器确认框
}
}, [shouldPrompt]);
// ? 在用户确认离开后，主动执行清理逻辑（注意：此函数不在 beforeunload 中调用！）
const cleanupOnLeave = useCallback(() => {
if (!shouldPrompt) return;
console.log('执行页面离开前清理：通知服务端并跳转');
// 1. 发送业务语义明确的离开事件（非 socket.disconnect()，因需携带上下文）
if (isHost && hasOpponent) {
socket.emit('new_host', room);
} else {
socket.emit('leave_room', room);
}
// 2. 立即跳转（避免用户看到白屏或残留 UI）
navigate('/');
}, [hasOpponent, isHost, navigate, room, shouldPrompt, socket]);
// ? 监听浏览器原生 unload 事件（比 beforeunload 更晚，但仍可执行轻量同步操作）
// ⚠️ 注意：unload 中不能保证异步操作完成，故只用于触发已注册的清理函数
useEffect(() => {
const handleUnload = () => {
if (shouldPrompt) {
cleanupOnLeave();
setShouldPrompt(false); // 防止重复执行
}
};
window.addEventListener('unload', handleUnload);
return () => window.removeEventListener('unload', handleUnload);
}, [cleanupOnLeave, shouldPrompt]);
// ? 同时监听 Socket 断连事件（兜底保障：网络异常/服务端踢出时也能清理）
useEffect(() => {
const handleSocketDisconnect = () => {
if (shouldPrompt) {
console.warn('Socket 异常断连，自动清理房间状态');
socket.emit('leave_room', room);
navigate('/');
}
};
socket.on('disconnect', handleSocketDisconnect);
return () => socket.off('disconnect', handleSocketDisconnect);
}, [room, navigate, shouldPrompt, socket]);
// ? 注册 beforeunload 监听（必须放在 useEffect 中，且依赖项完整）
useEffect(() => {
window.addEventListener('beforeunload', handleBeforeUnload);
return () => window.removeEventListener('beforeunload', handleBeforeUnload);
}, [handleBeforeUnload]);
// 其他组件逻辑...
return <div>...</div>;
}
export default Game;? 关键注意事项
- 不要在 beforeunload 中调用 socket.emit、navigate 或 setState：这些操作在事件上下文中不可靠，且 React 组件可能已进入卸载阶段。
- unload 事件仍属同步上下文，仅适合触发已准备好的清理函数，避免新增异步任务（如 await fetch()）。
- socket.disconnect() ≠ 业务断连：直接调用 socket.disconnect() 会关闭整个连接，而业务上通常需要先发 leave_room 通知服务端释放资源，再断连。因此优先使用 emit + 服务端响应逻辑。
- shouldPrompt 的作用不仅是控制弹窗，更是防止多次触发清理：一旦用户确认离开，立即将其置为 false，避免 unload 和 disconnect 事件重复执行。
- 移动端 Safari 对 beforeunload 支持有限：部分 iOS 版本会忽略自定义提示文本，仅显示默认提示。建议在关键场景（如对局中）增加页面内悬浮提示作为补充。
✅ 总结
可靠的页面离开控制 = 声明式提示（beforeunload） + 命令式清理（unload / disconnect 监听）。通过分离关注点，既满足浏览器安全策略，又保障了实时通信的业务一致性。对于游戏、协作编辑、在线会议等强状态场景，这一模式是生产环境的最佳实践。
? 提示：若需更高定制化弹窗（如含“保存并离开”按钮），必须放弃 beforeunload，改用路由守卫（如 useBlocker）+ 手动管理导航状态，但需自行处理所有退出入口（地址栏输入、前进/后退、关闭标签页等）。
