唯一长期安全的迁移路径是改用color.adjust()等模块化函数并禁用全局调用；Dart Sass 1.95.0起对lighten()等发出[global-builtin]警告，3.0.0将彻底移除，因其已从全局作用域移出，仅保留向后兼容的“影子调用”。
直接改用 color.adjust()、color.mix() 等模块化函数，同时禁用全局调用方式，是唯一长期安全的迁移路径。Dart Sass 1.95.0 起已对 lighten()、darken() 等发出 [global-builtin] 警告，3.0.0 版本将彻底移除它们。
为什么不能继续用 lighten($color, 10%) 这类写法
这类函数早已从全局作用域移出，仅保留向后兼容的“影子调用”。Dart Sass 的模块系统要求显式导入与命名空间隔离——不加 @use "sass:color" 就调用 lighten()，本质是绕过类型检查和作用域控制，属于被明确标记为“即将删除”的行为。
常见错误现象包括：
- 编译时出现
Deprecation Warning [global-builtin]: Global built-in functions are deprecated... - 升级到 Dart Sass ≥1.95.0 后，部分构建工具（如 Vite +
sass插件）可能静默忽略警告，但 CI 环境或新机器上直接报错中断 - 与
@use并存时出现命名冲突：比如你定义了$lighten: true，再写lighten($c, 10%)，Sass 会先查变量而非函数，报Undefined function
color.adjust() 替代 lighten()/darken() 的参数差异
color.adjust() 不是简单替换，它把颜色通道抽象为键值对，语义更清晰、组合更灵活，但参数结构完全不同。
立即学习“前端免费学习笔记（深入）”；
-
lighten($color, 10%)→color.adjust($color, $lightness: 10%) -
darken($color, 10%)→color.adjust($color, $lightness: -10%) -
transparentize($color, 0.2)→color.adjust($color, $alpha: -0.2) -
opacify($color, 0.2)→color.adjust($color, $alpha: 0.2)
注意：color.adjust() 不支持百分比单位缩写（如 10），必须带 %；且不接受负百分比以外的负值（比如 $lightness: -200% 会被截断为 -100%）。
迁移时最容易踩的三个坑
实际项目中，以下问题高频出现且难以定位：
-
混用旧函数与新模块：写了
@use "sass:color"，但仍写lighten($c, 10%)—— 这不会报错，但触发弃用警告；必须统一改为color.adjust()或color.lighten()（后者是模块内封装的别名，但官方不推荐依赖） -
第三方库未适配：比如 Bootstrap 4.x 或某些老旧 UI 库仍硬编码
darken()，@use导入会失败；只能 fork 修改，或临时降级 Sass 至 1.62.1（仅限过渡） -
主题色 map 遍历时漏改：用
@each $name, $color in $theme-colors批量生成禁用态颜色时，若内部仍调用darken($color, 30%)，整个循环都会触发警告——必须同步改成color.adjust($color, $lightness: -30%)
真正麻烦的不是语法替换，而是确认所有颜色操作都落在模块函数路径下。哪怕只漏一个 mix() 调用，CI 就可能卡在警告级别提升的临界点上。
