最常见的是 Module build failed: TypeError: this.getOptions is not a function，或 Cannot find module 'sass'、Node Sass version X.X.X is incompatible；根本原因是 sass-loader 与 sass（或 node-sass）版本不匹配，尤其 Next.js 中混用已废弃的 node-sass 和新版 sass-loader 会直接导致兼容性断裂。
SCSS模块构建失败的典型报错是什么
最常见的是 Module build failed: TypeError: this.getOptions is not a function，或直接提示 Cannot find module 'sass'、Node Sass version X.X.X is incompatible。这类错误基本不是 SCSS 语法问题，而是构建链路中 loader 或编译器版本不匹配导致的。
sass-loader 和 sass 版本必须严格对齐
Next.js 默认使用 sass（Dart Sass）而非已废弃的 node-sass。如果你手动安装了 node-sass 或旧版 sass-loader，就会触发兼容性断裂。
-
sass-loader@14.x要求sass@1.70.0+（Next.js 14.2+ 内置支持） -
sass-loader@13.x对应sass@1.60–1.69 - 绝对不要混用
node-sass和新版sass-loader——node-sass已于 2023 年终止维护，Next.js 13.4+ 完全弃用
验证方式：运行 npm list sass sass-loader，确保二者 major 版本协同（例如都为 v1.75.x + v14.2.x）。
Next.js 项目中无需手动配置 sass-loader
Next.js 内置 SCSS 支持，只要装对依赖，.module.scss 或 .scss 文件就能开箱即用。手动在 next.config.js 里加 webpack rule 反而会覆盖默认配置，引发重复解析或 loader 冲突。
立即学习“前端免费学习笔记（深入）”；
- ✅ 正确做法：
npm install sass --save-dev（仅此一条命令） - ❌ 错误操作：安装
sass-loader、css-loader、mini-css-extract-plugin等底层 loader - ⚠️ 若已有自定义 webpack 配置，请删除所有与
test: /\.(scss|sass)$/相关的 rule
示例正确导入方式（在客户端组件中）：
"use client";
import styles from './Button.module.scss';
export default function Button() {
return <button className={styles.primary}>Click</button>;
}
SCSS 文件被忽略或未生效的隐藏原因
即使编译不报错，样式也可能不出现——这通常和组件类型或导入位置有关。
- 服务端组件（无
"use client"）中 import.module.scss：类名会被生成，但 CSS 不注入，className值为空字符串 - 全局 SCSS（如
app/globals.scss）未在app/layout.tsx中 import：整个文件被跳过，零效果 - 路径错误或大小写不符（尤其 Windows/macOS 混合开发时）：
import './button.module.scss'和实际文件名Button.module.scss不匹配
检查方法：打开浏览器 DevTools → Elements → 找对应元素，看 class 属性是否为空或为原始字符串（非哈希值），即可反推是否走通了 CSS Modules 流程。
真正卡住的地方往往不是语法或变量，而是 loader 版本锁死、手动干预默认配置、或把 SCSS 当成普通 JS 模块去“执行”。Next.js 的约定大于配置，越少动 webpack，越容易跑通。
