Turbopack 当前不支持 .module.scss 模块化,仅识别 .module.css;SCSS 模块需手动编译为 .module.css 才能获得哈希类名、导出对象和细粒度 HMR。

不能靠“配置”提速,Turbopack 对 SCSS 的极速编译只在满足显式 import + 模块化路径 + 零 RSC 边界干扰的前提下成立;直接写 @import 或放 /public 里就彻底退出 HMR 链路。
为什么 import './Button.module.scss' 不生效
Turbopack 当前(2026年11月)**不识别 .module.scss 后缀为模块化 CSS**。它只对 .module.css 做哈希类名、导出对象、细粒度 HMR 处理;.module.scss 被当作普通 SCSS 文件处理——无作用域隔离、无导出、修改后触发整页刷新。
- ✅ 正确做法:用
.module.css写组件样式,SCSS 功能仅用于全局或工具层(如styles/utils/_mixins.scss) - ✅ 全局 SCSS 必须走
import './styles/main.scss'(且该文件最终@use或@import所有子模块) - ❌ 不要命名成
Button.module.scss并期待自动加载或局部作用域——Turbopack 会忽略其模块语义 - ⚠️ 若坚持用 SCSS 模块化,需手动编译为
.module.css(如通过sass --load-path=styles src/Button.scss dist/Button.module.css),再import
import 语句写在哪,决定了 HMR 是“毫秒级”还是“全页刷”
不是所有 import 都被 Turbopack 纳入增量缓存图。关键看它是否处于可热更新的 JS 模块链中,且不跨 RSC 边界。
- ✅ 安全位置:在
app/layout.tsx、app/page.tsx、components/Button.tsx(含'use client')顶部静态import - ❌ 危险位置:
-
app/loading.tsx或app/error.tsx中import—— 这两个文件属于 RSC 边界,HMR 支持极弱 -
use client组件内用import()动态加载 SCSS —— Turbopack 不支持动态 CSS 导入的 HMR -
app/layout.tsx里用dangerouslySetInnerHTML注入—— 完全绕过构建系统
-
- ⚠️ 注意:即使路径合法,若 SCSS 文件里用了
url('./icon.svg')且该 SVG 未被 Turbopack 显式识别为资源(比如没放在app/下或没被import过),也会中断构建图,退化为 full rebuild
PostCSS 和 Sass 编译链不能“自己配”,但能控制输入源头
Turbopack 内置 Dart Sass 和 PostCSS(含 autoprefixer),但不接受自定义配置。所谓“极速”,本质是它跳过了 Webpack 式的 loader 链解析,直接用 Rust 层预编译。你唯一可控的是 SCSS 文件如何组织与引用。
- ✅ 推荐结构:
-
styles/base/_variables.scss(只存变量、函数、mixin) -
styles/components/_button.scss(只写样式规则,@use '../base') -
styles/main.scss:只做@use汇总,不做实际样式声明
-
- ✅ 在
app/layout.tsx中import '../styles/main.scss'—— 这样 Turbopack 能把整个 SCSS 图纳入单次增量缓存 - ❌ 避免在多个
page.tsx中分别import '../styles/components/_button.scss'—— 每个 import 都可能触发独立重编译,增加 cache miss 概率 - ⚠️
browserslist仍需存在(如package.json中),否则autoprefixer不知道补哪些前缀;但无需配postcss.config.js—— Turbopack 忽略它
真正卡住极速编译的,往往不是 SCSS 语法本身,而是 import 位置、资源路径、RSC 边界这三处隐性断点。改一个变量后看到终端打出 [turbopack] rebuilding (full),说明其中一环已经断裂——此时检查 import 语句所在文件类型和路径,比调 Sass 编译参数更有效。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











