HMR不生效主因是链路中断，首查import.meta.hot是否为undefined；需确保入口JS存在、@vite引入正确路径、禁用host:'0.0.0.0'、CSS静态导入、清除.vite缓存并禁用浏览器缓存。
热更新不生效，大概率不是Vite坏了，而是HMR链路在Laravel里被掐断了——import.meta.hot为undefined就是最直接的证据。
检查 import.meta.hot 是否存在
打开浏览器开发者工具 Console，输入 import.meta.hot 并回车。如果返回 undefined，说明 HMR 运行时根本没加载进来，后续所有 CSS 修改都会静默失效。
- 常见原因：入口文件（如
resources/js/app.js）顶部没有import './bootstrap';或import '../css/app.css';；这行缺失，@vite插件就不会注入 HMR 客户端脚本 - 路径大小写必须完全匹配磁盘真实文件名（例如
App.css和app.css在 Linux/macOS 下是两个不同文件） - 确保 Blade 模板中调用的是
@vite(['resources/js/app.js'])，而不是只传 CSS 路径（@vite(['resources/css/app.css'])会静默失败）
server.host 设为 '0.0.0.0' 会切断 HMR
Vite 默认通过 WebSocket 推送更新，但浏览器出于安全限制，拒绝连接 0.0.0.0 地址上的 WS。一旦 vite.config.js 中写了 host: '0.0.0.0'，HMR 就彻底失联。
- 必须删掉该配置，或改为
host: true（让 Vite 自动绑定可用地址） - 这个坑特别常见于 WSL、Docker 或某些 IDE 内置终端启动场景，别把它当成“兼容性补丁”保留
CSS 必须静态 import，禁用动态引入和深层 @import
Vite 的 CSS HMR 只跟踪静态导入路径。任何运行时拼接、条件加载或嵌套 @import 都会让监听失效。
立即学习“前端免费学习笔记（深入）”；
- ❌ 错误写法：
import(`./themes/${theme}.css`)、@import './base.css'; @import './utils.css';（后者若utils.css再@import其他文件，就超出 Vite 监听深度） - ✅ 正确做法：所有样式统一在
app.js顶部用import '../css/app.css';引入；需要主题切换时，改用 CSS 变量 + JS 控制，而非多文件 import - ⚠️ 不要依赖
@vite(['resources/css/app.css'])单独引入 CSS —— Laravel-Vite 插件要求至少一个 JS 入口，否则整个指令不生效
缓存干扰比想象中更顽固
即使代码和配置全对，node_modules/.vite 缓存或浏览器对 text/css 响应的强缓存也会让更新“看起来没发生”。
- 必须执行：
rm -rf node_modules/.vite→ 关闭npm run dev→ 重新启动 - 浏览器 DevTools Network 标签页中，勾选 “Disable cache”；同时确认响应头中
Cache-Control不是max-age=31536000这类长效缓存 - 如果用了 Tailwind，还要检查
tailwind.config.js中的content路径是否覆盖到当前模板，否则生成的 CSS 文件里压根没有你写的类名
最容易被忽略的一点：HMR 更新 CSS 是替换 <style> 标签内容，但浏览器未必立刻重绘——哪怕控制台显示 “Updated” 日志，也建议手动触发一次 DOM 变更（比如加个空格再删掉），确认是不是渲染层卡住了。
