CSS热更新丢失主因是文件未纳入HMR链路或客户端未应用变更，可通过Network面板查请求状态、--debug css看日志、时间戳注释验证文件是否重发来精准定位。
热更新 CSS 丢失不是随机故障，而是文件未被正确纳入 HMR 链路或客户端未能应用变更——绝大多数情况能通过 Network 面板一眼定位。
检查 CSS 文件是否真被重新请求
这是最直接的判断依据。打开浏览器 DevTools → Network → Filter 输入 css，改一次目标 CSS 文件后观察：
- 如果该文件没出现在列表里，说明 Vite 根本没监听到改动（
chokidar漏掉了） - 如果出现了但状态码是
304 Not Modified，说明服务端没返回新内容，浏览器用了缓存 - 如果状态码是
200但样式仍没变，说明客户端 HMR 逻辑没执行替换（比如<link>被动态移除、或样式注入被拦截）
验证更简单：在 CSS 文件顶部加一行注释 /* hot: ${Date.now()} */，保存后看时间戳是否变化。不变化＝没重发请求＝问题出在服务端监听层。
确认 CSS 是否被动态加载绕过 Vite 解析
Vite 的 CSS HMR 只对通过模块系统导入的 CSS 生效。以下写法会彻底脱离 HMR 管控：
立即学习“前端免费学习笔记（深入）”；
fetch('/src/assets/theme.css').then(r => r.text()).then(css => { document.head.appendChild(Object.assign(document.createElement('style'), {textContent: css})) })-
<style scoped>@import './reset.css';</style>（reset.css是相对路径但没带./，Vite 不识别为模块） -
import.meta.env.DEV && import('./debug.css')（条件导入可能被 tree-shaking 排除）
这类代码不会触发 vite:css-transform 钩子，也不会出现在 HMR 日志中。用 vite --debug css 启动，改文件后若日志无对应 change 事件，基本坐实。
排查 Less/Sass 变量注入类 CSS 的 HMR 失效
如果你用 additionalData 注入全局变量（如 @import "@/styles/variables.less"），那它大概率根本没被 Less 加载：
- Less 不解析别名，
@/在编译时已失效，必须用path.resolve(__dirname, 'src/styles/variables.less') - Windows 下拼接路径用
__dirname + '/src/...'会产生反斜杠，导致路径解析失败 - Less 6+ 默认
javascriptEnabled: false，@import会被静默忽略，必须显式设为true -
modifyVars和additionalData同时存在时，前者对@import进来的文件无效，变量优先级混乱
验证方式：在 variables.less 第一行加 @debug "loaded";，终端没输出＝没加载；有输出但样式不变＝哈希不匹配或 HMR 替换失败。
留意 CSS Modules 类名哈希冲突导致整页刷新
当修改一个 CSS Module 文件却触发全页刷新，而不是局部样式更新，大概率是 localsConvention 配置破坏了哈希一致性：
- 错误配置：
localsConvention: 'camelCaseOnly'强制只生成驼峰类名，但旧模块记录的是默认哈希（含短横线），HMR 匹配失败后降级为 reload - 正确做法：
localsConvention: 'camelCase'（允许两种格式共存） + 显式指定generateScopedName - 注意：修改此配置后需手动清除浏览器缓存或重启 dev server，否则旧哈希仍残留于 HMR runtime 中
这种问题只影响 CSS Module，普通 CSS 不会触发整页刷新。用 --debug hv 启动可看到日志里明确打出 page reload 而非 css-update。
真正难缠的点在于：HMR 丢失往往没有报错，只有“无声失效”。关键不是猜原因，而是用 Network 面板确认请求是否发出、用 --debug css 看日志是否触发、用 @debug 或时间戳注释验证文件是否进入构建流水线——三步做完，90% 的 CSS 热更新问题就定位清楚了。
