HMR失效需逐层验证：先确认import.meta.hot是否可用，再检查Vite监听、TS代码规范及环境干扰。关键点包括vite.config.ts中hmr配置、tsconfig.json的types声明、watch轮询启用、避免顶层副作用、路径大小写一致等。
排查 TypeScript 项目中 Vite 模块热更新（HMR）失效，关键不是“猜”，而是按信号链逐层验证：从浏览器是否收到更新、Vite 是否监听到变更、代码是否符合 HMR 规范，再到环境是否干扰监听。下面分四类常见原因直接定位问题。
检查 import.meta.hot 是否可用
这是 HMR 的入口开关。在任意 .ts 或 .vue 文件中加一行：
console.log('HMR available:', import.meta.hot)
如果输出 false 或 undefined，说明 HMR 根本没启用：
OpenGemini Next.js Bestpractice Builder
下载
使用固定的 Next.js/Tailwind/Prisma 技术栈构建并记录独立 SaaS 项目，仅将 FastAPI 用于 Python 工作负载，并遵循严格的架构规范。
- 确认
vite.config.ts中未显式关闭：server.hmr: false→ 改为true或删掉该配置（默认开启） - 检查是否在非开发模式下运行（如误用
vite build启动 dev server） - TypeScript 项目需确保
types: ["vite/client"]已加入tsconfig.json的compilerOptions.types，否则类型提示可能掩盖实际缺失
验证文件变更是否被 Vite 监听到
Vite 依赖底层文件系统事件，某些环境会静默失败：
- 打开终端，修改一个 .ts 文件后观察控制台——是否有类似
[vite] hot updated: /src/App.vue或changed file日志？没有则监听失效 - 常见干扰场景：WSL2、Docker 容器、NFS 挂载目录、VS Code 远程开发 → 需强制启用轮询：
server: { watch: { usePolling: true, interval: 1000 } } - 检查是否误将源码目录加入
server.watch.ignored（如错误写成['src/**']）
确认 TS 代码写法未破坏 HMR 流程
TypeScript 本身不阻断 HMR，但特定写法会让模块无法被安全替换：
- 避免在顶层作用域执行副作用（如直接调用
router.push()、document.title = 'xxx'），这些操作会在模块重载时重复触发 - Vue 组件中，
setup()返回的对象必须是响应式声明（ref/reactive），而非普通对象字面量；否则状态无法保留 - 动态导入路径含变量（如
import(`./modules/${name}.ts`)）→ HMR 无法追踪依赖，改用静态字符串或预定义映射
排除缓存与环境干扰
即使 HMR 正常工作，也可能因缓存看不到效果：
- 浏览器 DevTools → Network → 勾选 “Disable cache”（仅在 DevTools 打开时生效）
- 清除 Vite 缓存：
rm -rf node_modules/.vite（macOS/Linux）或rimraf node_modules\.vite（Windows） - 检查文件路径大小写：TS 对路径敏感，
import '@/components/MyComp.vue'但实际文件是mycomp.vue→ HMR 失效（尤其 macOS/Windows 不区分大小写但 Vite 区分） - Node.js 版本建议 ≥ v20.19.0（Vite 6+ 推荐），旧版本在 ESM 动态导入处理上存在兼容性问题
