uniapp项目Sass升级全攻略：从node-sass到dart-sass

最近帮一位做 uniapp 小程序的同事排查编译报错项目一跑就是Node Sass version 6.0.1 is incompatible with ^4.0.0他照着网上的教程换版本装包折腾半天项目直接起不来了。这类问题我处理过太多次说句实话大多数时候难的不是安装命令本身而是很多人没搞清楚你的 uniapp 项目到底走的是哪条 Sass 编译链路。写这篇东西就是把 HBuilderX 和 uniapp 项目里升级 Sass 版本的完整思路梳理一遍帮大家少走弯路。内容会覆盖几个最关键的环节先判断项目属于哪条编译链路再讲清楚 Sass 相关依赖的版本搭配规则然后给出不同场景下的实操步骤最后是升级之后最常碰到的语法迁移和报错排查。无论你是刚入行的前端还是被历史项目坑过的老手照着这篇去处理基本都能有个明确方向。1. 升级前先分清HBuilderX内置编译与CLI项目是两条路1.1 node-sass和dart-sass别再傻傻分不清先解决一个最基础的认识问题。很多人提到 Sass 就笼统认为是一个东西但实际上现在有两种主流实现而且它们的宿命完全不同。第一种是node-sass底层是 LibSass用 C 写的。由于是编译型二进制node-sass在安装时要下载对应你本地 Node 版本的.node文件。这个二进制文件和 Node 版本严格绑定Node 升一个小版本它可能就要重新下载甚至直接报错。最坑的是 LibSass 官方早早就宣布进入维护模式不再跟进新语法新版本 Node 也不适配了。换句话说这个项目已经在“慢性死亡”的路上。第二种是dart-sass也就是现在 npm 上直接装sass拿到的包。Dart Sass 虽然底层也是编译型语言但发布到 npm 的版本是用 JS 编译好的对 Node 版本宽容得多不需要匹配二进制语法跟进也快。官方现在的推荐方向就是 dart-sass新写的项目、新升级的项目都应该朝着这个方向走。换句话说你只要看到node-sass还在 package.json 里躺着就说明这个项目的 Sass 链路还停留在旧时代升级的第一步基本就是把它换掉。1.2 HBuilderX内置编译器与CLI项目的编译链路差异这一节是整个升级动作里最重要的一环。uniapp 项目有两种典型的构建方式升级 Sass 时的操作路径完全不同。第一种是 HBuilderX 内置编译器。你在 HBuilderX 里新建项目、直接点“运行到小程序模拟器”或“运行到浏览器”如果项目根目录没有package.json或者没有安装本地依赖编译动作全部由 HBuilderX 自带的编译插件完成。此时 Sass 的解析器是哪来的是 IDE 内置的不读你项目里的node_modules。好处是开箱即用坏处是版本被 HBuilderX 锁死你自己根本改不了。第二种是 CLI 项目。项目根目录有package.json依赖由 npm/yarn 管理编译时由 webpack 或 vite 调用本地node_modules里的 Sass 编译你的 scss 文件。这种模式下你可以自由控制 Sass 版本想装哪个装哪个。怎么判断自己属于哪种很简单打开项目根目录看有没有package.json和node_modules。另外看 HBuilderX 控制台输出如果编译日志里出现了本地依赖路径说明走的是 CLI如果日志里只有 HBuilderX 自身的插件路径那基本就是内置编译器。1.3 什么情况会逼你不得不升级Sass那什么时候需要做升级这件事我总结了几个常见场景第一编译直接报错。最常见的像Node Sass version ... is incompatible with ...、this.getOptions is not a function、Cannot find module sass这些基本都是依赖版本错乱导致的。第二新语法不支持。比如你想在 scss 里用use、math.div这些新特性但旧版 Sass 编译器根本不认识编译直接失败或者明明语法正确却提示错误。第三安装阶段就过不去。node-sass装到一半报错下载binding.node失败这在新版 Node 环境下太常见了。第四历史项目移交维护。接手的项目里还锁着一个三年前的node-sass版本为了以后维护不难受通常都会选择做一次升级。不管是哪种情况动手之前搞懂项目走哪条链路永远是第一优先级。2. 版本搭配不对装了也白装sass/sass-loader/构建工具怎么选2.1 核心版本对应关系一览升级 Sass 不是说把sass包换成最新版本就完事它牵扯到sass-loader、webpack/vite、Node 版本等多个因素。我整理了一份比较常见的搭配关系大家可以先对照自己项目的技术栈。构建工具链推荐 sass 版本推荐 sass-loader 版本备注vue2 webpack4vue-cli 4/5sass 1.69.xsass-loader 10.x稳定组合大量实战项目验证vue3 webpack5sass 1.69.xsass-loader 13.x也可考虑 sass-loader 14但需 Node 18vue3 vitesass 1.69.x不需要 sass-loadervite 内置了 Sass 预处理器支持HBuilderX 内置编译由 IDE 控制不可选只能升级 IDE 或切换 CLI 项目这里要特别说下sass-loader的版本坑。sass-loader10.x 还兼容 webpack 4到了 11.x 开始就只支持 webpack 5 了。如果你的 uniapp 项目是 vue2 webpack4 的底子把sass-loader升到 12 或 13编译的时候大概率会报一个this.getOptions is not a function原因就是新版sass-loader调用了旧版 webpack 不存在的 API。很多人升级失败其实就是栽在这个版本错配上。2.2 vue2 webpack4 的 uniapp 项目推荐组合vue2 的 uniapp 项目数量还是非常大的这种项目升级 Sass 我推荐锁定这样一套组合sass1.69.5sass-loader10.4.1。为什么不直接升到 Sass 最新版因为 Sass 官方从 1.80 左右开始密集输出各种 deprecation 警告尤其是针对import的移除计划。如果你的项目里全是老式import写法的公共样式升级到新版本后编译日志会被大量黄色警告刷屏虽然暂时不影响产物但看着真的很难受还会干扰你排查其他问题。1.69.5是最后一个在“支持新语法”和“兼容老代码”之间比较平衡的版本。为什么sass-loader要用 10.x因为 uniapp vue2 项目基本都是基于 webpack 4sass-loader 10.x 是兼容 webpack 4 的最高主版本稳定、成熟网上能搜到的坑也基本被踩光了。2.3 vue3 vite 的 uniapp 项目推荐组合vue3 的 uniapp 项目分两种一种是 vite 构建一种是 webpack5 构建。如果是 vite记住一句话只装sass本体不装sass-loader。vite 内部已经集成了 Sass 的预处理能力它只需要你在项目里装上sass就能直接编译 .scss 文件。如果你额外装一个sass-loader反而可能出现重复处理、配置冲突这种奇怪问题。如果是 vue3 webpack5 的 uniapp 项目那sass-loader选 13.x 比较稳。同时注意 Node 版本要在 18 及以上否则部分依赖可能会报环境不满足。2.4 升级前的准备工作升级构建依赖属于动手术级别的操作准备工作不做足出了问题容易手忙脚乱。我自己的习惯是第一步先git status看看工作区是否干净有未提交的改动就先 commit 一次。这样升级失败随时能回退相当于给自己留一张后悔药。第二步备份package.json和package-lock.json或者yarn.lock。即使有 git单独备份一份也更稳妥方便对比到底哪里变了。第三步确认本地的 Node 版本。执行node -v然后对照一下准备安装的依赖是否兼容。新版 Node 建议直接放弃 node-sass 相关方案别给自己找罪受。第四步想好用哪个包管理器。uniapp 项目里 npm 最通用yarn 次之pnpm 在一些老项目里容易出现 peer 依赖的兼容问题。如果是历史项目建议保持原来的包管理器不要升级依赖的同时顺手换包管理器一次改变的变量越少越好。3. 实操3种场景下的Sass升级步骤含命令3.1 场景一HBuilderX内置编译器项目怎么处理如果你确认项目走的是 HBuilderX 内置编译器那有一个残酷的事实要先接受你自己很难直接指定 Sass 的版本因为解析器是 IDE 内置的。这种情况下我能给出的可操作性建议有三条按优先级排列第一升级 HBuilderX 本身。HBuilderX 的版本更新会同步更新内置工具链你只要打开 HBuilderX菜单栏找到“运行 - 检查更新”升到最新版本内置的 Sass 编译器版本也就跟着变新了。第二试试“本地依赖优先”的方案。在项目根目录创建package.json然后按后面场景二或场景三的命令安装本地sass依赖。据我实测部分 HBuilderX 版本在检测到项目里有本地依赖时会优先使用本地的 Sass 来编译。但这里要强调不完全确定每个版本都支持所以装完之后一定要跑一次编译观察控制台输出用的是内置插件路径还是本地node_modules路径。第三如果前两条都行不通那就只能考虑把项目改成 CLI 模式了。说句实话这个改造工程比较大不建议单纯为了升级 Sass 就动这个手术。更现实的做法是升级 HBuilderX 到最新然后检查代码里有没有用到内置编译器不支持的新语法有就做兼容没有就正常用着。3.2 场景二vue-cli创建的vue2项目完整升级命令这是最常见的场景步骤我给你写全。打开命令行进入项目根目录先卸载旧依赖npm uninstall node-sass sass-loader注意这里卸载的是node-sass不是sass。如果项目里已经装了sass可以保留也可以顺便卸载后重装确保版本统一。接着安装推荐组合npm install -D sass1.69.5 sass-loader10.4.1安装完成后验证一下 Sass 版本npx sass --version正常会输出类似1.69.5 compiled with dart2js这样的信息。这一步能确认你实际使用的 Sass 解释器版本。然后跑一次编译npm run dev:mp-weixin或者跑 H5 端npm run dev:h5如果编译通过、页面正常升级就完成了。如果报错直接看第 4 章的排查表。这里有一个细节要提醒vue2 项目的vue.config.js里如果有手动配置过css.loaderOptions.sass升级完要检查一下字段名。旧版 sass-loader 用的是prependData新版更推荐additionalData。如果这个配置没生效你在uni.scss里定义的全局变量可能在组件里全部失效样式会乱掉。3.3 场景三vite创建的vue3项目升级更简单vite 项目的升级相对干净。先卸载可能存在的旧依赖npm uninstall node-sass sass-loader然后直接安装 Sass 本体npm install -D sass1.69.5这里不需要sass-loader再次强调。装完后运行npm run dev:h5vite 会启动开发服务并自动编译。如果项目是 HBuilderX 创建的 vue3 项目检查一下根目录有没有vite.config.js一般不需要额外修改只要sass装好了就能识别 .scss 文件。有一个额外提醒如果你用的 vite 版本比较新启动时可能看到一条关于legacy JS API的 deprecation 警告。这条警告暂时不影响编译结果可以忽略不用为了消除警告去折腾配置。3.4 升级后如何验证编译与产物升级完不能只看编译不报错就算完事我一般会做三件事确认一切正常。第一确认版本。npx sass --version看到的目标版本号要和 package.json 里的一致。第二验证新语法。在任意一个 vue 文件的style langscss里写一段新语法测试比如use sass:math; .test-width { width: math.div(100, 3) * 1%; }如果编译通过说明新语法已经被正确解析。如果报错说明编译链路还没真正切到新版 Sass。第三检查全局变量和业务样式。找一个用到了uni.scss全局变量的页面确认样式正常再检查深选择器样式::v-deep、/deep/在 H5 和小程序端表现一致。这一步容易被忽略但恰恰是线上样式出问题的高发区。4. 升级后马上要面对的语法迁移与报错排查4.1 旧语法兼容import、除法、颜色函数怎么改Sass 版本升级后最让人头疼的不一定是安装过程而是项目里沉淀了几年的旧语法。这里挑三个最常见的问题说。第一个是import的迁移。新版 Sass 官方推荐用use和forward替代import。但注意use的变量作用域是局部的引入的变量默认不能直接访问需要写use xxx as *才能把变量挂到当前作用域。如果你的老项目到处都在用全局变量升级后别急着把所有import改成use因为改动量非常大还容易漏改导致变量找不到。我的建议是先把版本升上来确保编译能跑通import暂时还能用后续再抽时间逐步迁移。第二个是除法运算。旧写法是width: (100 / 3) px;新版会提示Deprecation Warning: / will be interpreted as division。正确做法是use sass:math; width: math.div(100, 3) * 1px;如果只是计算布局比例也可以直接用 CSS 原生的calc(100% / 3)不需要 Sass 参与。第三个是颜色函数。darken($color, 10%)、lighten($color, 10%)这些老函数在 dart-sass 里还保留着能用但官方推荐迁移到更语义化的color.adjust、color.scale。这一项不紧急属于代码规范层面的优化有空再改。4.2 常见报错与解决方案速查表升级后跑编译必然会遇到一些报错。我把实际项目里最常碰到的几种整理成了一张表遇到问题直接对照排查。报错信息原因解决办法Node Sass version x.x.x is incompatible with ^y.y.y项目里还残留 node-sass版本和 sass-loader 要求不匹配卸载 node-sass换用 sassthis.getOptions is not a functionsass-loader 版本过高不兼容 webpack 4降级到 sass-loader 10.xCannot find module sass只装了 sass-loader没装 sass 本体执行npm install -D sassSassError: expected {新版 Sass 对语法格式检查更严格常见于漏括号、缩进混乱检查对应 scss 文件语法补全括号Deprecation Warning: / will be interpreted as division代码里用了旧式除法改为math.div或calc()Cant find stylesheet to importuse或import的文件路径不对检查路径、文件名引入时省略_前缀和.scss后缀4.3 uni.scss全局变量与样式穿透的注意事项uniapp 和其他普通 Vue 项目有个明显区别就是根目录下有个uni.scss文件。这个文件很特殊它编译时会被自动注入到每个组件的样式块开头所以你在里面定义的变量、mixin 可以全局直接用不需要每个组件手动import。升级之后这个全局注入机制要重点验证。如果你发现升级前能用的变量升级后组件里undefined了大概率是 sass-loader 版本变化导致prependData/additionalData配置没生效。检查一下 vue.config.js 或 vite.config.js 里的 loader 配置确认uni.scss的注入路径没错。样式穿透方面/deep/、::v-deep、:deep()这些选择器的支持情况不直接取决于 Sass 版本更多是取决于 Vue 的 scoped 方案和构建工具。但实际经验里有个小坑同一段::v-deep .class-name写法在 H5 端编译正常在小程序端可能解析出错。升级 Sass 后建议尽量统一写成::v-deep(.class-name)这种函数式写法兼容性最好。5. 我踩过的坑node-sass、版本锁定与编译缓存5.1 一次node-sass安装失败的完整排查记录有一次帮朋友处理项目npm install报错日志里一大段红色核心信息是下载binding.node失败。第一反应是网络问题让他重试了几次还是失败。进一步排查后发现他本地的 Node 已经升到了 18而他项目里锁的node-sass是 4.14 版本这个版本根本还没有适配 Node 18 的预编译二进制安装时只能尝试在线编译编译过程中又缺少本机编译工具链最后以失败告终。这种情况下的唯一彻底解法就是放弃 node-sass迁移到 dart-sass。和朋友们也交流过很多人遇到这类问题第一反应都是网上搜“node-sass 安装失败怎么办”然后配置镜像、换源、重试折腾一大圈还是时不时的装不上。我的看法是node-sass 本身已经进入遗留状态不要在它身上花太多精力趁早迁移到 dart-sass 才是正道。5.2 关于版本锁定我个人的习惯在升级完 Sass 之后我强烈建议你把版本精确锁定而不是用^或者~。比如在 package.json 里写{ devDependencies: { sass: 1.69.5, sass-loader: 10.4.1 } }这样写的好处是团队里任何人npm install拿到的都是完全一致的版本不会出现“你本地编译没问题我编译就报错”这种经典问题。同时package-lock.json一定要提交进 git。这个文件的定位就是锁住完整依赖树的如果忽略它相当于给你的团队埋了一颗定时炸弹。新成员拉代码后安装依赖建议使用npm ci而不是npm install。npm ci会严格按 lock 文件安装不会做任何版本浮动装完的依赖和线上一致。5.3 保持编译稳定的几个小技巧最后分享几个升级之后让编译更稳定的小技巧。第一清缓存。升级完依赖或者改完 sass 相关配置后如果发现样式没生效、编译行为怪异优先清一次缓存。HBuilderX 项目在“运行”菜单里有清除编译缓存的选项CLI 项目可以直接删除unpackage目录下对应端的编译缓存文件夹然后重新编译。这招能解决很多“明明改了却像没改”的问题。第二在 uniapp 项目里生产环境的 sourceMap 建议关闭。小程序包体本身有大小限制Sass 的 sourceMap 会额外增加产物体积而且大多数情况下你用不到它。在配置文件里把css.sourceMap关掉编译速度和产物体积都能得到优化。第三不要频繁在 Sass 大版本之间横跳。今天升到 1.85明天觉得警告烦又退回 1.69来回切换不仅浪费时间还可能导致 lock 文件混乱。锁一个稳定版本用一段时间确认没有问题再考虑升级。第四不同端要统一验证。uniapp 项目经常要跑 H5、微信小程序、App 三端Sass 升级后建议三个端都编译一次。因为三端的底层构建链路不完全相同可能出现 H5 正常但小程序样式错乱的诡异情况。多花十分钟跑一遍能避免线上事故。最后再分享一点个人的体会。uniapp 项目里升级 Sass最难的不是安装那一下而是很多人根本没搞清楚自己项目走的是哪条编译链路。内置编译器、vue-cli、vite三种情况的操作路径完全不同用错方案只会越搞越乱。我现在的习惯是新项目统一用 CLI 方式创建Sass 直接用 dart-sass老项目如果锁定在 HBuilderX 内置编译先评估整体诉求再决定是否改造。另外说句实在话动手改构建依赖之前一定记得先提交一次代码给自己留好后悔药。这个步骤看着多余但真到编译崩了的时候你会感谢那个多敲了一行 git 提交的自己。