Sass 模块化革命

为什么你的 Sass 代码突然开始报错？是时候彻底理解 Sass 的模块化系统了！

最近很多前端开发者突然发现自己的 Sass 代码开始报出各种警告和错误：

• @import rules are deprecated
• There's already a module with namespace "math"
• Using / for division is deprecated

这一切都源于 Dart Sass 的模块化革命。如果你还在使用传统的 @import，那么这篇文章将带你彻底理解新的模块系统，并手把手教你如何迁移。

为什么要弃用 @import？

传统 @import 的问题

让我们先回顾一下 @import 的常见用法：

$primary-color: #1890ff;
$font-size: 14px;

// main.scss
@import "variables";
@import "mixins";
@import "components/button";

.button {
  color: $primary-color;
  font-size: $font-size;
}

variables.scss

看起来很简单对吧？但 @import 有几个致命缺陷：

• 全局污染：所有变量、mixin、函数都混入全局作用域
• 无法避免冲突：同名变量会被覆盖，且很难追踪来源
• 无法控制可见性：无法隐藏私有变量
• 性能问题：每次 @import 都会重新计算
• 依赖混乱：无法知道模块间的依赖关系

新系统的优势

@use 和 @forward 组成的模块系统解决了所有这些问题：

• 命名空间隔离：每个模块有自己的作用域
• 明确的依赖关系：清晰知道每个变量来自哪里
• 更好的封装：可以隐藏私有成员
• 更快的编译：模块只被计算一次

核心概念：@use vs @forward

@use：使用模块

@use 用于在当前文件中使用其他模块的功能。

// 基本用法
@use "sass:math";
@use "variables";

// 通过命名空间访问
.element {
  width: math.div(100%, 3);
  color: variables.$primary-color;
}

// 使用通配符（类似旧版行为）
@use "variables" as *;
.element {
  color: $primary-color; // 直接使用，无需前缀
}

// 自定义命名空间
@use "variables" as vars;
.element {
  color: vars.$primary-color;
}

@forward：转发模块

@forward 用于转发模块的成员，但不直接使用它们。常见于库的入口文件。

// 转发整个模块
@forward "variables";

// 选择性转发
@forward "sass:math" show div, ceil, floor;
@forward "components/button" hide _private-mixin;

// 重命名转发
@forward "sass:math" as math-*;
// 使用时会变成：math-div(), math-ceil()

实战迁移指南

场景1：基础变量和工具迁移

迁移前（@import）：

$primary-color: #1890ff;
$border-radius: 4px;

// styles/mixins.scss
@mixin rounded-corners($radius: $border-radius) {
  border-radius: $radius;
}

// main.scss
@import "styles/variables";
@import "styles/mixins";

.button {
  color: $primary-color;
  @include rounded-corners;
}

styles/variables.scss

迁移方案A：直接使用

@use "styles/variables" as vars;
@use "styles/mixins";

.button {
  color: vars.$primary-color;
  @include mixins.rounded-corners;
}

main.scss

迁移方案B：创建库入口

// styles/_index.scss （库入口）
@forward "variables";
@forward "mixins";

// main.scss
@use "styles" as *; // 所有成员直接可用

.button {
  color: $primary-color;
  @include rounded-corners;
}

场景2：处理第三方库冲突

问题场景： 第三方库和你的代码都需要 sass:math

// ❌ 可能冲突的情况
// element-plus 内部已使用: @use "sass:math" as math;
// 你的代码中也使用: @use "sass:math" as math;

// ✅ 解决方案1：使用不同命名空间
@use "sass:math" as original-math;

.element {
  width: original-math.div(100%, 3);
}

// ✅ 解决方案2：创建包装函数
// utils/_math-utils.scss
@use "sass:math" as sass-math;

@function divide($a, $b) {
  @return sass-math.div($a, $b);
}

// 使用
@use "utils/math-utils" as math;
.element {
  width: math.divide(100%, 3);
}

场景3：构建组件库

项目结构：

ui-library/
├── foundation/
│   ├── _variables.scss
│   ├── _colors.scss
│   └── _index.scss
├── components/
│   ├── _button.scss
│   ├── _card.scss
│   └── _index.scss
└── index.scss

配置入口文件：

// ui-library/foundation/_index.scss
@forward "variables";
@forward "colors";
@forward "typography";

// ui-library/components/_index.scss
@forward "button" show button, button-variants;
@forward "card" show card;
// 隐藏私有成员
@forward "modal" hide _private-styles;

// ui-library/index.scss
@forward "foundation";
@forward "components";

// 业务代码中使用
@use "ui-library" as ui;

.custom-button {
  @extend ui.button;
  background-color: ui.$primary-color;
}

常见陷阱和解决方案

陷阱1：命名空间冲突

// ❌ 错误：相同的命名空间
@use "module1" as utils;
@use "module2" as utils; // 错误：命名空间 "utils" 重复

// ✅ 正确：使用不同的命名空间
@use "module1" as utils1;
@use "module2" as utils2;

陷阱2：@use 和 @forward 顺序错误

// ❌ 错误：@forward 必须在 @use 之前
@use "sass:color";
@forward "sass:math"; // 错误！

// ✅ 正确：正确的顺序
@forward "sass:math"; // 先转发
@use "sass:color";    // 后使用

陷阱3：忽略除法运算迁移

// ⚠️ 警告：传统除法将弃用
$ratio: 16/9; // 警告：Using / for division is deprecated

// ✅ 正确：使用 math.div()
@use "sass:math";
$ratio: math.div(16, 9);

陷阱4：在 @forward 文件中直接使用转发的成员

// utils/_index.scss
@forward "math-tools";

// ❌ 错误：不能在转发文件中直接使用转发的成员
$value: math.div(100, 2); // 错误！math 不可用

// ✅ 正确：需要单独 @use
@use "sass:math" as math;
$value: math.div(100, 2);
@forward "math-tools";

自动化迁移工具

Sass 官方提供了强大的迁移工具：

# 安装迁移工具
npm install -g sass-migrator

# 1. 迁移 @import 到 @use
sass-migrator import-to-use **/*.scss

# 2. 迁移除法运算
sass-migrator division **/*.scss

# 3. 同时处理多种文件类型
sass-migrator import-to-use --recursive "**/*.{scss,sass,vue}"

# 4. 带参数的迁移
sass-migrator import-to-use --namespace=lib "src/**/*.scss"

最佳实践总结

命名策略

// 基础变量 → 通配符导入（方便使用）
@use "variables" as *;

// 工具函数 → 命名空间导入（避免冲突）
@use "utils/math" as math;

// 第三方库 → 使用短命名空间
@use "element-plus" as ep;

文件组织

// 库/框架：使用 @forward 构建清晰的API
// _index.scss
@forward "foundation" show $colors, $typography;
@forward "components" hide _private-*;
@forward "utilities" as utils-*;

// 业务代码：使用 @use 明确依赖
@use "ui-library" as ui;
@use "project/utils" as utils;

处理依赖关系

// 依赖图：A → B → C
// c.scss
$value: red;

// b.scss
@use "c" as *;
$color: $value;

// a.scss
@use "b" as *;
.element { color: $color; }

性能优化建议

• 减少重复计算：模块只计算一次，即使被多次 @use
• 合理使用缓存：构建工具通常会缓存编译结果
• 避免深层嵌套：过深的 @forward 链可能影响性能
• 按需导入：使用 show/hide 只导入需要的成员

版本兼容性

// package.json 版本建议
{
  "devDependencies": {
    "sass": "^1.58.0",     // 支持完整模块系统
    "sass-loader": "^13.2.0"
  }
}

写在最后

迁移到新的 Sass 模块系统看起来有些挑战，但带来的好处是实实在在的：

• 🎯 代码更清晰：明确的依赖关系和命名空间
• 🔧 维护更容易：模块化的结构便于重构
• ⚡ 性能更好：智能的缓存和编译优化
• 🚀 面向未来：符合现代前端开发的最佳实践

*迁移不是一次性的痛苦，而是一次性的投资。*现在花时间迁移，未来将节省大量的调试和维护时间。

记住这个简单的决策流程：

1. 构建库/框架 → 优先使用 @forward
2. 编写业务代码 → 主要使用 @use
3. 基础变量/配置 → 考虑 @use ... as *
4. 工具函数 → 使用命名空间避免冲突

行动起来吧！ 从今天开始，逐步将你的项目迁移到新的模块系统。你的未来代码库会感谢你现在做出的努力！