本文详解如何在 vite 开发服务器中彻底禁用热模块替换（hmr），避免长时间操作（如大文件上传、复杂计算）因页面自动刷新而中断进度，同时提供配置示例与关键注意事项。
本文详解如何在 vite 开发服务器中彻底禁用热模块替换（hmr），避免长时间操作（如大文件上传、复杂计算）因页面自动刷新而中断进度，同时提供配置示例与关键注意事项。
在基于 Vite 的 React（或其它框架）开发中，热模块替换（HMR）默认处于启用状态，它能快速局部更新组件逻辑，提升开发体验。但当应用涉及耗时较长的用户交互流程（例如：大型数据导入、Canvas 渲染动画、表单分步提交、WebSocket 长连接状态维持等），HMR 触发的自动更新会强制重载模块甚至整个页面，导致内存状态丢失、加载中断、进度归零——这不仅影响调试效率，更可能掩盖真实业务逻辑缺陷。
要完全禁用 HMR（即关闭所有热更新行为，包括模块级更新和页面自动刷新），只需在 vite.config.ts 的 server 配置项中将 hmr 显式设为 false：
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
export default defineConfig({
plugins: [react()],
server: {
host: true,
port: 5173,
hmr: false, // ? 关键配置：彻底禁用 HMR
// 注意：无需再配置 hmr.overlay 或 watch.usePolling —— 它们在 hmr: false 下自动失效
}
});✅ 效果说明：
- 文件保存后，Vite 将不再尝试注入 HMR 客户端脚本；
- 浏览器控制台不会出现 [vite] hot updated: 日志；
- 页面不会自动刷新或局部更新，开发者需手动按 F5 或点击浏览器刷新按钮触发全量重载；
- 所有运行时状态（如 React 组件内部 useState、useRef、全局变量、Web Worker 状态、未持久化的 Canvas 上下文等）将完整保留，直到你主动刷新。
⚠️ 重要注意事项：
- hmr: false 是全局禁用，适用于调试特定长流程场景，不建议长期用于日常开发，否则将失去 Vite 快速迭代的核心优势；
- 若仅想抑制 HMR 引发的错误覆盖层（如语法错误弹窗），应使用 hmr: { overlay: false }，而非关闭整个 HMR；
- 禁用 HMR 后，import.meta.hot API 将不可用，相关自定义热更新逻辑（如 accept()、invalidate()）将被忽略；
- 此配置不影响 Vite 的其他能力（如 ES 模块解析、TypeScript 编译、CSS 处理等），构建生产包（npm run build）行为完全不受影响。
? 进阶建议：
若你希望在部分模块（如 src/utils/longTask.ts）中保留状态、但又不想完全关闭 HMR，可考虑结合 import.meta.hot?.decline() 主动声明“拒绝更新”，或使用 useEffect + cleanup 模拟轻量级状态保持。但对于明确需要全程无干扰的调试场景，hmr: false 仍是最直接、最可靠的解决方案。
