项目应使用 sass 而非 node-sass，需清理旧包、禁用 --watch、单次编译、统一路径分隔符、清理缓存并锁定 node 版本、确保 sass-loader 与 webpack 兼容，并完成 @import 到 @use 的迁移。
确认项目用的是 sass 而不是已废弃的 node-sass
CI 失败最常见原因就是两者混用或残留旧包。执行 npm list node-sass sass 检查输出：
- 如果同时出现
node-sass和sass，立刻删掉node-sass：npm rm node-sass --save-dev - 如果只看到
node-sass，说明项目还在用旧链路，必须替换为sass：npm add sass --save-dev -
sass是纯 JS 实现，不依赖 Python/make/node-gyp，CI 容器里无需额外装构建工具
在 CI 脚本中禁用 sass --watch，改用一次性编译命令
sass --watch 是开发时用的监听模式，在 CI 中会挂住不退出，导致流水线卡死。
- 正确做法是单次编译：
sass src/scss/:dist/css/ --style=compressed --no-source-map -
--style=compressed直接生成压缩版 CSS，省去额外 postcss 或 clean-css 步骤 -
--no-source-map关掉 sourcemap（CI 通常不需要），避免因权限或路径问题报错 - 路径分隔符统一用正斜杠
/，Windows CI 镜像也认，反斜杠\在 YAML 中易被误解析
CI 脚本开头必须清理缓存并锁定 Node 版本
本地能跑、CI 崩了，90% 是因为 node_modules 缓存污染或 Node 版本漂移。
- 脚本开头加：
rm -rf node_modules package-lock.json，强制干净安装 - 显式指定 Node 版本：GitHub Actions 用
uses: actions/setup-node@v3+node-version: '20'；GitLab CI 写image: node:20.15 - 避免 npm 缓存干扰：
npm ci --no-audit --no-fund，比npm install更可靠 - Docker 构建时，确保
RUN npm ci前工作目录已清空，旧层里的node_modules可能含损坏的二进制绑定
Webpack 项目中注意 sass-loader 和 sass 的版本兼容性
如果你用 Webpack 打包，sass-loader 必须匹配 Webpack 版本，且底层依赖的仍是 sass 包。
- Webpack 5 对应
sass-loader@13.x、sass@1.77+；用^自动升级容易引入不兼容小版本 - 检查
sass-loader的peerDependencies，它要求的sass版本范围必须和你装的一致 - 报错
this.getOptions is not a function就是sass-loader和 Webpack API 不对齐，需降级或锁死版本
最容易被忽略的是 @import 到 @use 的迁移——Dart Sass 已弃用全局作用域，旧写法在 CI 中可能静默失败或生成错误 CSS，必须提前在本地完成迁移验证。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
