本文介绍在 vite + react 项目中彻底禁用热模块替换（hmr）的方法，解决因自动重载导致长时间加载任务中断、状态丢失的问题，并提供配置示例与关键注意事项。
本文介绍在 vite + react 项目中彻底禁用热模块替换（hmr）的方法，解决因自动重载导致长时间加载任务中断、状态丢失的问题，并提供配置示例与关键注意事项。
在开发大型 React 应用时，某些功能（如大数据初始化、复杂模型加载或长耗时计算）可能需要数秒甚至数十秒完成。此时若 Vite 的热更新（HMR）被触发（例如保存代码），页面将自动刷新或局部重载，导致所有前端状态清空、加载进度归零——严重影响调试效率与开发体验。
Vite 默认启用 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, // ✅ 关键：彻底禁用热模块替换
// 注意：无需再配置 watch.usePolling 或 hmr.overlay
}
});
⚠️ 重要说明：
- hmr: false 是 Vite 4.3+ 版本起支持的官方配置项，兼容 Vite 4.4.9 及更高版本；
- 禁用 HMR 后，文件变更将不再触发任何自动更新（既无热替换，也无页面刷新），开发者需手动按 F5 或点击浏览器刷新按钮来查看变更效果；
- 若你仍希望保留「全量页面刷新」能力（即修改后自动 reload 整页，而非 HMR），可配合 server.hmr.overlay 和 server.watch 进行精细控制，但注意：hmr: false 本身已隐含禁用所有自动更新逻辑，watch 配置在此场景下不再影响重载行为；
- 此配置仅作用于开发服务器（vite dev），对构建产物（vite build）无任何影响，生产环境本就不含 HMR。
✅ 推荐实践：
对于存在长耗时初始化逻辑的页面，建议在开发阶段临时禁用 HMR；上线前恢复默认配置以保障开发效率。也可通过环境变量实现条件化配置：
server: {
hmr: process.env.DISABLE_HMR !== 'true', // 运行时控制：vite dev DISABLE_HMR=true
}
总之，hmr: false 是解决加载中断问题最直接、最可靠的方案，简洁高效，且无副作用。
