标签： node-sass

从 node-sass 迁移到 Dart Sass 的实践与踩坑

背景

在前端开发中，Sass 是一种流行的 CSS 预处理器，它为 CSS 添加了变量、嵌套、混合等特性，使样式代码更加模块化和可维护。长期以来，node-sass 是 Node.js 环境中使用 Sass 的主要方式，它是对 LibSass（C++ 库）的封装。

然而，随着技术的发展，node-sass 已被官方标记为过时，并推荐使用 Dart Sass（即 sass 包）作为替代。本文将分享我们在一个 Vue 2 项目中从 node-sass 迁移到 Dart Sass 的实践经验和遇到的问题。

迁移的必要性

为什么要从 node-sass 迁移到 Dart Sass？主要有以下几个原因：

  1. 官方支持：LibSass 已于 2020 年停止开发，而 Dart Sass 是 Sass 官方的主要实现，会持续获得新功能和更新。
  2. 安装问题：node-sass 依赖于 LibSass，需要在安装时编译二进制文件，经常因为环境问题导致安装失败。
  3. 兼容性：随着 Node.js 版本的更新，node-sass 的兼容性问题越来越明显。
  4. 新特性：Dart Sass 支持最新的 Sass 语法和特性，如模块系统等。

迁移步骤

1. 更新依赖

首先，我们需要移除 node-sass 并安装 sass：

// package.json
{
"devDependencies": {
// "node-sass": "^4.14.1", // 移除
"sass": "^1.86.2", // 添加
"sass-loader": "^7.3.1" // 保持兼容的版本
}
}

2. 处理语法兼容性问题

迁移后，我们遇到了第一个问题：构建时出现了大量警告，提示 >>> 深度选择器语法已过时。在 Vue 2 中，深度选择器用于修改子组件的样式，特别是在使用 scoped 样式时。

问题示例：

// 旧语法
.parent >>> .child {
color: red;
}

Dart Sass 警告这种语法将在未来版本中被移除，需要替换为新的语法。

3. 批量修复深度选择器

为了解决这个问题，我们创建了一个脚本来批量替换项目中所有 Vue 文件中的 >>> 选择器：

const fs = require('fs');
const path = require('path');
const { promisify } = require('util');

const readFile = promisify(fs.readFile);
const writeFile = promisify(fs.writeFile);

// 递归获取所有 .vue 文件
async function getAllVueFiles(dir) {
const files = await promisify(fs.readdir)(dir);
const vueFiles = [];

for (const file of files) {
const filePath = path.join(dir, file);
const stat = await promisify(fs.stat)(filePath);

if (stat.isDirectory()) {
const subFiles = await getAllVueFiles(filePath);
vueFiles.push(...subFiles);
} else if (file.endsWith('.vue')) {
vueFiles.push(filePath);
}
}

return vueFiles;
}

// 修复文件中的 >>> 选择器
async function fixFile(filePath) {
try {
const content = await readFile(filePath, 'utf8');

// 使用正则表达式查找并替换 >>> 选择器
const newContent = content.replace(/>>>\s*\./g, '/deep/ .');

// 如果内容有变化，写入文件
if (content !== newContent) {
await writeFile(filePath, newContent, 'utf8');
console.log(`Fixed: ${filePath}`);
return true;
}

return false;
} catch (error) {
console.error(`Error processing ${filePath}:`, error);
return false;
}
}

// 主函数
async function main() {
const srcDir = path.join(__dirname, 'src');
const vueFiles = await getAllVueFiles(srcDir);

console.log(`Found ${vueFiles.length} Vue files`);

let fixedCount = 0;

for (const file of vueFiles) {
const fixed = await fixFile(file);
if (fixed) {
fixedCount++;
}
}

console.log(`Fixed ${fixedCount} files`);
}

main().catch(console.error);

运行这个脚本后，我们成功修复了 56 个文件中的深度选择器语法。

4. 处理深度选择器语法错误

然而，在修复后的构建过程中，我们遇到了新的错误：

error in ./src/views/tariffSettings/index.vue

Module build failed:
}
^
Expected selector.
╷
46 │ }
│ ^
╵
stdin 46:2 root stylesheet

这是因为我们的批量替换脚本没有考虑到深度选择器的上下文。在 Vue 2 + Sass 中，/deep/ 选择器不能单独使用，它必须附加在一个父选择器后面。

错误代码：

// 错误语法
/deep/ .el-tabs__nav-wrap::after {
height: 0px !important;
}

修复方法：

// 正确语法
.lym-lay01 /deep/ .el-tabs__nav-wrap::after {
height: 0px !important;
}

我们需要手动修复这些特殊情况，确保每个 /deep/ 选择器都有一个父选择器。

5. 处理内存溢出问题

在使用 Dart Sass 构建大型项目时，我们遇到了另一个问题：Node.js 内存溢出。

<--- Last few GCs --->
[12956:000001E06CB2A7A0] 166286 ms: Mark-sweep (reduce) 4092.4 (4104.5) -> 4092.1 (4105.3) MB, 1503.1 / 0.1 ms (average mu = 0.209, current mu = 0.014) allocation failure scavenge might not succeed

FATAL ERROR: MarkCompactCollector: young object promotion failed Allocation failed - JavaScript heap out of memory

这是因为 Dart Sass 比 Node Sass 消耗更多内存。Node Sass 是对 C++ 库的封装，直接使用系统资源，而 Dart Sass 是用 Dart 语言编写后编译成 JavaScript，在 Node.js 环境中运行，内存管理效率较低。

解决方案：

修改 package.json 中的构建脚本，增加 Node.js 的内存限制：

"scripts": {
"build": "node --max-old-space-size=8192 build/build.js"
}

这将 Node.js 的内存限制提高到 8GB，足以应对 Dart Sass 的内存需求。

深度选择器的正确用法

在 Vue 2 中，深度选择器有三种写法，但都需要与父选择器结合使用：

  1. 使用 /deep/（推荐）：

    .parent /deep/ .child { ... }

  2. 使用 >>>（已过时）：

    .parent >>> .child { ... }

  3. 使用 ::v-deep：

    .parent ::v-deep .child { ... }

注意：在 Vue 3 中，这些语法都已更改为 :deep()。

批量修复脚本的改进

基于我们的经验，可以改进批量修复脚本，使其能更准确地处理各种情况：

// 更精确的替换逻辑
const newContent = content
// 处理已有父选择器的情况
.replace(/([.#][^{]*)\s*>>>\s*\./g, '$1 /deep/ .')
// 处理没有父选择器的情况（添加一个通用父选择器）
.replace(/^(\s*)>>>\s*\./gm, '$1.parent-selector /deep/ .');

经验总结

  1. 渐进式迁移：在大型项目中，最好采用渐进式迁移策略，先更新依赖，然后逐步解决兼容性问题。

  2. 自动化工具：使用脚本批量处理重复性问题，但要注意处理特殊情况。

  3. 深度选择器规范：

    • 始终将深度选择器与父选择器结合使用
    • 在新代码中统一使用推荐的语法
    • 考虑将这一规范添加到团队的代码规范文档中

  4. 性能优化：

    • 增加 Node.js 内存限制
    • 优化 Sass 文件，减少嵌套层级
    • 考虑使用缓存提高构建性能

  5. 测试验证：修改后务必全面测试，确保样式渲染正常，特别是那些使用了深度选择器的组件。

结论

从 node-sass 迁移到 Dart Sass 是一个必要的升级，虽然过程中会遇到一些挑战，但通过合理的策略和工具，可以顺利完成迁移。这不仅解决了当前的兼容性问题，还为未来的升级和维护打下了基础。

最佳实践是在迁移前充分了解两者的差异，准备好应对可能出现的问题，并利用自动化工具提高效率。通过本文分享的经验，希望能帮助其他团队更顺利地完成类似迁移。