改了CSS页面没反应，大概率是CSS未被import显式引入，从而完全绕过HMR链路；必须用import './xxx.css'，禁用<link>、动态fetch或style插入，否则不触发热更新。
改了 CSS 页面没反应，大概率不是 HMR 失效，而是该 CSS 根本没进 HMR 链路——Vite 和 Turbopack 对 CSS 的热更新都极度依赖“是否被 import 显式引入”这一条铁律。
CSS 必须通过 import 引入，不能靠 <link> 或动态插入
浏览器里改完 button.css 没变化？先查它是不是被 import 了。Vite 和 Turbopack 的 HMR 都只监听模块图内路径，<link rel="stylesheet" href="/css/button.css"> 完全绕过构建系统，等于直接读取静态文件，自然不触发热更新。
- ✅ 正确写法：
import './button.css'（在入口 JS 或组件中） - ❌ 错误写法：把 CSS 放
/public/css/下，再用<link>加载 - ⚠️ 动态插入也失效：
fetch('/src/styles/button.css').then(...)或document.createElement('style')不会被监听
Vite 中 CSS 修改后无响应？先验证是否真发起了请求
加一行注释是最快验证方式。在 CSS 文件顶部插入：/* hot: ${Date.now()} */，保存后打开浏览器 Network 面板，过滤 css，看该文件是否以状态码 200 重新请求。没重发？说明文件变更根本没被 dev server 捕获。
- 常见原因：路径别名未被 Vite 解析（如用了
@/styles/button.css但vite.config.ts里没配resolve.alias） - watch 失效可能因系统限制：可临时加
server.watch.usePolling: true排查 - Tailwind class 变更没生效？确认
tailwind.config.js中content字段包含所有 HTML/JSX 路径，否则 JIT 不会生成对应样式
Turbopack 下的 CSS Modules 与全局样式必须手动区分
Turbopack 不靠配置开关，而靠文件名约定决定作用域行为。写错后缀，样式就“漏出”到全局或完全不生效。
立即学习“前端免费学习笔记（深入）”；
-
Button.module.css→ 自动启用 CSS Modules，导出对象如{ button: 'Button_button__abc123' } -
globals.css或index.css→ 默认全局作用域，类名不哈希化，也不导出 -
Button.module.scss或.less→ Turbopack 当前（v1.0+）不识别，需预构建为 CSS 后再import - PostCSS/Tailwind 必须提前处理好：Turbopack 不支持运行时插件，
@tailwind指令必须已在 CSS 文件中展开完毕
HMR 卡顿或退化为全量刷新？重点检查 React Server Component 边界
Turbopack 的增量更新很敏感，尤其在 Next.js App Router 场景下。某些位置的 CSS import 会强制触发整页 reload，而非局部样式替换。
- 修改
app/layout.tsx中import '../styles/globals.css'→ 通常仍为局部更新 - 修改
app/loading.tsx或app/error.tsx中 import 的 CSS → 很可能触发边界重载（RSC 边界不可局部热更） - 在
use client组件里用import()动态加载 CSS → Turbopack 不支持，直接 fallback 到 full reload - 终端出现
[turbopack] rebuilding (full)→ 检查是否有eval、new Function或未声明全局变量污染了模块作用域
真正卡住调试的，往往不是工具不行，而是 CSS 被悄悄移出了模块图——比如条件 import、被 tree-shaking 掉的分支、或 IDE 自动补全出来的错误路径。每次怀疑 HMR 失效，先做两件事：加时间戳注释看 Network，再顺一遍 import 链是否完整连到入口。
