Vite中SCSS热更新后CSS不刷新的修复方法

需要先明确一点：安装 Sass 是有版本要求的，必须使用 ≥1.70.0 的版本，否则 Vite 无法正常编译 SCSS，也不能正确触发 HMR 热更新。另外，@import 并不支持路径别名，因此要改成相对路径，或者通过配置 includePaths 搭配 @use 来处理。除此之外，像 variables.scss 这类被依赖的样式文件，还需要借助 server.watch.ignored 进行显式监听，才能确保样式修改后 CSS 及时刷新。

检查 sass 是否已正确安装并启用

Vite 对 SCSS 热更新的支持，依赖于 sass（Dart Sass）在运行时完成编译。这并不是可选插件，而是必须安装在 devDependencies 中，并且能够被 Vite 自动调用。如果你安装的是已经废弃的 node-sass，或者根本没有安装 sass，那么 Vite 往往只会退回到“解析 import 路径”的模式，导致 SCSS 不会真正编译，HMR 热更新自然也无法生效。

可通过以下命令进行确认：

• npm list sass 或 yarn list sass —— 必须有输出，推荐版本 ≥ 1.70.0
• 如果没有输出：npm install sass -D
• 删除 node_modules/.vite 目录后，重新执行 npm run dev

避免 @import 路径别名失效导致 HMR 断链

在 SCSS 文件中写 @import "@/styles/variables.scss"; 看起来没问题，但实际上 Vite 的 CSS HMR 并不会处理 CSS/SCSS 层级的路径别名解析。因为 @import 是由 Sass 引擎执行的，而像 @/ 这样的别名解析属于 Vite 在 JS 模块层完成的能力。结果就是：目标文件可能根本没有被真正加载，你即使修改了 variables.scss，也不会触发任何 HMR 更新日志。

验证方法也很简单：在 variables.scss 第一行加入 // debug: loaded，保存后观察终端是否出现 [vite] hot updated: 日志。没有日志，就说明文件变化没有被监听到。

修复方案可二选一：

• 改成相对路径：@import "../styles/variables.scss";（最稳定，也最不容易产生歧义）
• 在 vite.config.ts 中配置 css.preprocessorOptions.sass.includePaths，并使用 @use（更推荐）：

  css: {
  preprocessorOptions: {
  sass: {
  includePaths: [path.resolve(__dirname, 'src/styles')],
  additionalData: '@use "variables" as *;'
  }
  }
  }

确认 @use / @forward 替代 @import 后 HMR 可正常追踪

Dart Sass 已经弃用 @import，而 @use 和 @forward 的模块化机制与 Vite 的依赖图兼容性更好。不过前提是：被 @use 引入的文件，必须能够被 Vite 的文件监听器直接识别，也就是说它需要位于 includePaths 的有效范围内，同时不能使用动态拼接路径。

常见问题包括：

• @use "@/styles/variables" → ❌ 别名无法解析，Sass 找不到对应文件
• @use "./variables"（当前目录中不存在）→ ❌ 路径错误，虽然编译失败，但 HMR 未必会明确提示
• @use "variables" + includePaths 配置正确 → ✅ 可以被监听，也能正常触发热更新

还要注意：additionalData 会被预先插入到每个 SCSS 文件开头，因此它引入的变量可以在所有 SCSS 文件中全局生效，无需重复书写 @use。也正因为如此，这类被全局注入的依赖文件必须加入 watchFiles 监听范围中（见下一条）。

手动添加 watchFiles 确保变量文件被监听

Vite 默认只会监听你显式 import 的 .scss 文件，不会递归追踪通过 @use 或 @import 间接引入的依赖文件。这就意味着：即使你修改了 variables.scss，Vite 也可能并不知道哪些文件依赖了它，因此不会通知浏览器刷新 CSS。

解决方式是在 vite.config.ts 的 SCSS 配置中，显式声明需要监听的范围：

export default defineConfig({
css: {
preprocessorOptions: {
sass: {
includePaths: [path.resolve(__dirname, 'src/styles')],
additionalData: '@use "variables" as *;'
}
}
},
// ? 关键：让 Vite 主动监听 variables.scss
server: {
watch: {
ignored: ['!**/src/styles/**/*.scss']
}
}
})

或者也可以更精细地借助插件方式处理，例如使用 vite-plugin-sass-dart，不过在原生 Vite 场景下，更推荐使用 server.watch.ignored 配合通配符来完成监听配置。修改后一定要重启 dev server，因为 watch 相关配置只会在启动时注册生效。

最后提醒一下：不要误以为“清理浏览器缓存”就能解决 Vite 中 SCSS 热更新后 CSS 不刷新的问题。只要控制台连 [vite] hot updated: 都没有输出，基本可以确定问题出在 Vite 的文件监听与依赖追踪链路上，而不是浏览器缓存层面。