Vite 修改 CSS 触发全页刷新是因为样式未被 JS 模块显式 import 或配置干扰导致 HMR 失效；正确方式是通过 import 语句引入 CSS，而非 HTML 的 <link> 标签或动态插入 style。
为什么 Vite 修改 CSS 会触发全页刷新而不是 HMR
这不是 CSS 本身的问题，而是 Vite 没能将样式变更识别为可热替换的模块更新。当修改 .css、.scss 或 .less 文件后整页 reload，说明 HMR 链路在样式层断开了——Vite 客户端没收到“仅更新样式”的指令，只能退回到最保守的兜底策略：刷新整个页面。
根本原因通常有两个：一是样式未被 JS 模块显式 import（比如只靠 HTML 的 <link> 引入），二是构建插件或配置干扰了样式注入流程，例如同时启用了 @vitejs/plugin-vue 和手动 style 标签注入逻辑，导致 HMR runtime 无法接管。
确认你的 CSS 是否走的是 HMR 可控路径
Vite 的 CSS HMR 依赖一个前提：样式必须作为 ES 模块被 JS 主动导入。否则它只是静态资源，不参与模块图，自然无法热更新。
- ✅ 正确方式（可 HMR）：
import './index.css'或import '@/styles/main.scss'写在main.ts、App.vue或某个被引用的组件中 - ❌ 错误方式（无 HMR）：
<link rel="stylesheet" href="/src/index.css">直接写在index.html里；或者通过第三方库（如某些 UI 组件库的自动注入）间接加载 - ⚠️ 特殊情况：使用
css-in-js库（如styled-components、emotion）时，HMR 行为由该库自身控制，Vite 不介入；需确认其 dev 模式是否启用热更新
检查 vite.config.ts 中的 CSS 相关配置冲突
某些看似无关的配置会悄悄禁用 CSS HMR，尤其是当你从 Webpack 迁移或叠加多个插件时。
立即学习“前端免费学习笔记（深入）”；
-
css.devSourcemap设为false一般不影响 HMR，但设为true在某些旧版 Vite（'inline' 或保持默认 - 如果你手动配置了
build.rollupOptions.plugins并插入了自定义 CSS 处理插件（比如重写transform钩子），它可能拦截了 Vite 原生的 HMR 注入逻辑 - 使用
@vitejs/plugin-react-swc时，若同时又装了@vitejs/plugin-react，二者对 JSX 中import的处理可能冲突，间接影响样式模块识别 - 确保没有全局禁用 HMR：
server.hmr: false或server.watch: { enabled: false }这类配置要彻底删除
Vue / React 项目中样式 HMR 失效的典型陷阱
框架层封装会掩盖底层机制，容易踩坑。
- Vue 单文件组件中：
<style scoped>是安全的，但<style module>需确保defineExpose或useCssModule()没被误用，否则模块 ID 不稳定，HMR 会失败 - React +
@vitejs/plugin-react：默认启用fastRefresh，它支持 CSS HMR，但若你在组件内写了useEffect(() => { ... }, [])并在里面动态创建<style>标签，这部分样式就脱离 HMR 管控 - 使用
postcss-import时，如果@import的路径是变量（@import url(${theme}.css)），Vite 无法静态分析依赖，该样式文件不会被纳入 HMR 监听范围 - SCSS 中的
@import 'xxx.scss'是 OK 的，但@use 'xxx'如果指向的是未被 JS 显式 import 的文件，也可能不触发 HMR
真正卡住的点往往不在“怎么开 HMR”，而在于“哪些代码会让 HMR 自动失效却不报错”。尤其要注意那些看起来只是“引入样式”的一行代码，背后是否绕过了模块系统。一旦样式脱离 import 链，Vite 就只剩 reload 这一条路可走。
