$variable: value !default 的真实作用是“仅当变量未被定义时才赋值”，它不覆盖已定义变量，仅对全局顶层变量有效，依赖 import 顺序，无法解决 css 层级或运行时配置问题。
什么是 $variable: value !default 的真实作用
它不是“定义变量”，而是“仅当变量未被定义时才赋值”。很多开发者误以为写了 !default 就能安全覆盖上级变量，结果在插件集成时发现自己的 $color-primary 根本没生效——因为宿主项目早已在 import 之前定义了同名变量，!default 直接跳过赋值。
- 必须确保插件的变量声明出现在宿主自定义变量之后，否则覆盖无效
-
!default只对顶层变量（global scope）有效，嵌套作用域里写没用 - 不能用于
@function或@mixin内部的局部变量 - 如果宿主用了
!important或内联 style，CSS 层级问题仍需单独处理，sass 变量不解决渲染优先级
怎么让插件用户真正“可覆盖”变量
关键不是堆 !default，而是控制 import 顺序 + 提供清晰的覆盖入口。典型错误是把所有变量和样式写在一个文件里，用户想改一个颜色却要 fork 整个文件。
- 把变量抽成独立文件，比如
_variables.scss，只放带!default的声明 - 在文档里明确写出“请在 import 插件前定义你的变量”，并给示例：
$btn-padding: 8px !default;<br>@import "my-plugin/variables";<br>@import "my-plugin/core"; - 避免在变量值里嵌套其他变量（如
$primary-dark: darken($color-primary, 10%) !default），因为darken()在变量未定义时报错，!default来不及兜底 - 对必须依赖的变量（如
$font-family-base），加注释说明“此变量无默认值，必须由宿主提供”
为什么 !default 在 CSS Modules 或 Vite 中容易失效
现代构建工具常做模块隔离或并发编译，Sass 变量的全局性被打破。你看到的 “变量已定义” 可能来自另一个 scope 的同一文件副本，或者被 CSS-in-js 工具提前编译掉了。
- Vite 默认启用
css.preprocessorOptions.sass.additionalData，若这里注入了变量，会覆盖插件里的!default - 使用
@use（而非@import）时，变量默认私有，!default行为完全不同：它只在当前模块内生效，无法被外部覆盖 - webpack 的
sass-resources-loader会把变量注入每个文件顶部，可能造成重复定义，导致!default完全不触发 - 调试方法：在插件变量文件末尾加
@debug $my-var;，看终端输出是否为预期值
替代方案：什么时候该放弃 !default
当插件需要支持主题切换、运行时换肤、或与 Tailwind 等原子类库共存时，!default 就力不从心了。它本质是编译期静态覆盖，不是运行时配置。
立即学习“前端免费学习笔记（深入）”；
- 对高频定制项（如颜色、圆角、间距），提供 CSS 自定义属性接口：
:root { --my-plugin-radius: 6px; }，再用var(--my-plugin-radius)替代 Sass 变量 - 用
@mixin封装可配置逻辑，比一堆!default更可控：@mixin my-btn($bg: $color-primary, $radius: $border-radius-sm) { ... } - 若必须用 Sass 变量，考虑导出函数式 API：
my-color("primary", "light")，内部查表返回，比硬编码变量更灵活
真正难的不是写 !default，而是判断哪些值该交给用户控制、哪些该锁死、以及控制权移交后如何不破坏原有样式链。变量覆盖只是起点，样式契约才是关键。