本文介绍在 vite + react 项目中彻底禁用热模块替换（hmr）的方法，避免长时间加载任务因自动刷新而中断，确保用户操作进度不丢失。
本文介绍在 vite + react 项目中彻底禁用热模块替换（hmr）的方法，避免长时间加载任务因自动刷新而中断，确保用户操作进度不丢失。
在使用 Vite 开发 React 应用时，其默认启用的热模块替换（HMR）机制虽能提升开发体验，但在某些特殊场景下反而成为干扰因素——例如执行耗时较长的数据初始化、大文件上传、复杂状态计算或模拟真实后端延迟等操作时，代码保存触发的 HMR 会强制刷新页面或局部重载组件，导致所有前端状态（如 loading 状态、临时表单数据、WebSocket 连接、Canvas 绘图上下文等）瞬间丢失，严重影响调试与功能验证。
要完全禁用 Vite 的自动重载行为，只需在 vite.config.ts 的 server 配置项中显式关闭 HMR：
// 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, // ? 关键配置：彻底禁用热模块替换
// 其他如 watch、overlay 等配置将被忽略（hmr: false 时自动失效）
}
});
✅ 效果说明：设置 hmr: false 后，Vite 将不再监听文件变更并推送更新，也不会注入 HMR 客户端运行时逻辑。此时修改源码仅会在控制台输出变更日志，浏览器页面将保持完全静止，无任何自动刷新或模块热替换发生。
⚠️ 注意事项：
- 禁用 HMR 后，你仍可通过手动刷新（Ctrl+R / Cmd+R）获取最新代码，开发流程变为“保存 → 手动刷新”；
- 若仅希望抑制错误覆盖层（overlay） 而非禁用 HMR（例如避免遮挡 loading 动画），应改用 hmr: { overlay: false } —— 但这不会阻止重载行为，仅隐藏报错弹窗；
- watch.usePolling 或 hmr.overlay 等配置在 hmr: false 下无效，无需保留；
- 生产构建（npm run build）不受此配置影响，HMR 本就不参与生产环境，因此该设置仅作用于 vite dev 模式。
? 进阶建议：若需在部分模块变更时强制整页刷新（而非 HMR），可参考 Vite 插件机制，通过 handleHotUpdate 钩子主动调用 this.send({ type: 'full-reload' })，实现更精细的刷新策略——但这属于定制化场景，常规需求推荐直接使用 hmr: false 简洁可控地解决问题。
总之，server.hmr = false 是 Vite 官方支持的、语义明确且零副作用的禁用方案，适用于所有需要稳定运行长周期前端任务的开发调试阶段。
