解决Next.js构建时SCSS模块生成CSS失败

在前端开发内容学习中，如何解决Next.js构建时SCSS模块生成CSS失败是常见主题。很多人在阅读时会遇到概念分散、步骤不清和注意点难以归纳的问题。本文按照基础概念、操作流程和关键细节，对相关内容进行整理。

最常见的是 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，就会触发兼容性断裂。

• [email protected] 要求 [email protected]+（Next.js 14.2+ 内置支持）
• [email protected] 对应 [email protected]–1.69
• 绝对不要混用 node-sass 和新版 sass-loader —— node-sass 已于 2024 年终止维护，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，越容易跑通。