直接换用 sass（Dart Sass）可解决 90% 的 Sass 编译失败问题，因其为纯 JS 实现、无二进制依赖、不依赖 Python 或构建工具，且全面支持现代 CSS/SCSS 语法；迁移需彻底卸载 node-sass 和 sass-loader，安装 sass 与 sass-loader@^13，并清除 node_modules 和配置中所有 require('node-sass') 残留。
绝大多数 Sass 编译报错根本不是语法写错了，而是底层编译器没装对、装不全，或者被旧版 node-sass 拖累——直接换用 sass（Dart Sass）能解决 90% 的“无法生成 CSS”问题。
为什么 sass 能一劳永逸替代 node-sass
node-sass 是基于已停更的 LibSass，依赖 C++ 编译和预编译二进制文件（binding.node），在 Node ≥18、M1/M2 Mac、Windows 下极易因 ABI 不匹配或网络问题失败；而 sass 是纯 JS 实现，npm install -D sass 秒装，无构建工具、无 Python、不卡 s3 下载，且自 v1.3.0 起全面支持 @use、CSS 嵌套、@layer 等现代语法。
- 执行
npm uninstall node-sass sass-loader（必须同时卸载两者，否则 loader 可能 fallback 到旧实现） - 再执行
npm install -D sass sass-loader@^13（sass-loader@13.3.2是 Webpack 5/Vite 最稳组合） - 删掉
node_modules和package-lock.json后重装，避免残留 require 路径冲突 - 检查配置里没有硬编码
implementation: require('node-sass')或nodeSass字段
@use 语法不合法导致编译中断
Dart Sass 对 @use 的位置和结构极其敏感：它必须出现在文件最顶部，不能嵌套、不能加条件、不能混用 @import。一旦违规，编译器会在词法解析阶段直接退出，不生成任何 CSS。
-
@use必须是 SCSS 文件第一行（@charset除外），前面不能有空行、注释或空格 - 禁止在
@media、@mixin或选择器块内部写@use - 不要混用
@import和@use：旧项目迁移时，先全局搜索@import并逐个替换为@use "path" as *或命名空间调用 - 如果
@use "@/styles/vars.scss" as *;报错，先确认vars.scss里只有变量、@mixin、@function，不能含body { }这类真实 CSS 规则
中文字符引发的两类静默失败
中文在 SCSS 中只允许出现在注释、字符串值或 CSS 属性值里；一旦出现在变量名、@mixin 名、选择器名或 @use 路径中，Dart Sass 会在 tokenization 阶段直接报错，且错误信息常被掩盖成 “Invalid CSS after” 或 “Undefined variable”。
立即学习“前端免费学习笔记（深入）”；
-
$主色: red;❌ 不合法 —— 变量名必须以字母或_开头，中文字符不在标识符范围内，转义（如$\4F59\8272）也不支持 -
@use "@/样式/vars.scss" as *;❌ 路径含中文会触发 Node.js 文件系统读取异常，尤其 Windows 下直接崩，错误提示类似ENOENT或乱码路径 - 全局搜索正则
\$[\u4e00-\u9fa5]或@use.*[\u4e00-\u9fa5]快速定位非法中文位置 - 所有 SCSS 文件必须保存为 UTF-8 without BOM，
@charset "UTF-8";必须为首行首字符（前面不能有任何空格/BOM）
rem() 函数升级后报 “2 arguments required”
Sass ≥1.65.0 将内置 rem() 从单参数改为双参数：rem($px, $base: 16px)。旧写法 rem(300) 会立即中断编译，且不生成 CSS。
- 正确写法：
width: rem(300, 16px);或统一定义变量：$root-font-size: 16px; width: rem(300, $root-font-size); - 临时兼容可锁定版本：
npm install sass@1.64.2 --save-dev，但仅限应急，该版本已无安全更新 - 注意：此错误不会被
sass-loader捕获并降级，而是由 Dart Sass 编译器直接抛出，阻断整个构建流程
真正难排查的不是报错本身，而是那些让编译器静默跳过文件的情况：比如第三方 SCSS 库里藏了中文变量、@use 路径拼错导致模块加载失败、或 additionalData 注入末尾漏了分号——这些都会让 CSS 输出为空，但控制台未必显示明确错误。
