Turbopack CSS热更新失效的三大静默原因：一是全局CSS未置于app/目录且未被app/layout.tsx顶部静态import；二是.module.css与普通.css混用或命名/导入方式错误；三是存在循环依赖导致HMR降级为全页重载。
不能靠“手动刷新”或“等构建完成”，Turbopack 的 CSS 热更新本应是毫秒级的——但一旦路径、导入方式或文件命名出错，它就会静默退化为全页重载。
全局 CSS 必须放在 app/ 目录下并由 app/layout.tsx 顶层 import
Turbopack 不扫描 src/、styles/ 或根目录下的 CSS 文件，也不处理 pages/_app.tsx 中的导入。它只认 app/ 下被 app/layout.tsx 静态引入的样式：
-
app/global.css✅ 合法路径；src/global.css❌ 完全忽略 -
import './global.css'必须写在app/layout.tsx文件最顶部，不能包裹在if、useEffect或函数里 - 若项目用了 App Router 却没定义
app/layout.tsx，Turbopack 不报错，但样式根本不会注入 HTML —— 这是最常被忽略的“失效无感”场景
.module.css 和普通 .css 混用会导致 HMR 失效
Turbopack 对两类 CSS 的处理机制完全不同：普通 .css 是全局注入，.module.css 是局部作用域 + 类名哈希。但命名错误会让 HMR 边界判断崩溃：
- 文件命名为
Button.module.css，却在layout.tsx中import './Button.module.css'→ Turbopack 无法将其识别为全局样式，也不触发模块热更新逻辑，结果是“改了没反应” - 想用模块样式？必须在组件中
import styles from './Button.module.css'，且该组件本身需被 HMR 边界正确包裹（即不能处于循环依赖链中） - 所有
import必须是 ESM 静态语法，require('./xxx.css')或动态import()均不参与 Turbopack 的样式依赖图构建
避免循环依赖，否则 HMR 会直接降级为 window.location.reload()
Turbopack 的 HMR 传播依赖精确的模块拓扑。当 A → B → A 形成环时，它无法确定从哪一端刷新状态，只能放弃局部更新：
立即学习“前端免费学习笔记（深入）”；
- 典型诱因：组件中
import了某个工具函数，而该工具函数又反向import了该组件（比如用于类型推导或 mock） - 检测手段：目前 Turbopack 自身不提供循环依赖警告，需借助
vite-plugin-circular-dependency（即使不用 Vite，其扫描逻辑仍适用）在本地预检 - 修复关键：把双向引用拆成单向 —— 工具函数不应依赖具体组件，可提取为纯数据结构或用回调参数替代直接引用
真正卡住热更新的，往往不是 Turbopack 本身，而是 app/layout.tsx 是否存在、import 是否静态、CSS 文件是否在正确路径——这三个点任意一个失效，HMR 就会从毫秒掉到秒级甚至全页重刷。它们不报错，只沉默失效。
