正确做法是用 map-merge 扩展 $theme-colors：先 @import functions 和 variables，再定义变体列表并合并，最后用 @each 遍历调用 button-variant() 生成完整状态样式。
如何用 Sass 列表定义按钮变体而不污染全局变量
Bootstrap 的 $theme-colors 是可扩展的，但直接追加会覆盖默认值或引发重复编译。正确做法是用 map-merge 扩展而非重写：
- 在自定义 Sass 文件中先
@import "bootstrap/scss/functions"和"bootstrap/scss/variables" - 用
$my-button-variants: ("ghost": #f8f9fa, "neon": #00f3ff)定义新变体列表 - 执行
$theme-colors: map-merge($theme-colors, $my-button-variants)，确保后续button-variant()能识别
漏掉 @import "functions" 会导致 map-merge 报错 Undefined mixin "map-merge" —— 这是新手最常卡住的地方。
为什么 button-variant() 循环生成的类名不生效
Bootstrap 5.3+ 的 button-variant() 是一个 mixin，它本身不自动循环；你必须手动用 @each 遍历 $theme-colors 并调用它：
@each $color, $value in $theme-colors {
.btn-#{$color} {
@include button-variant($value, $value, $value);
}
}
常见错误包括：
- 忘记包裹
@each，直接写@include button-variant(...)→ 只生成一个默认变体 - 传参顺序错：
button-variant()第一参数是背景色，第二是边框色，第三是文字色；传反会导致文字不可见 - 未在
button-variant()后显式设置border-color→ 某些主题下 hover 状态边框消失
如何让自定义按钮支持 disabled 和 :hover 状态样式
原生 button-variant() 已内置状态逻辑，但前提是你的自定义颜色在 $theme-colors 中且被 @each 正确遍历。关键检查点：
- 确认
$value是合法 CSS 颜色值（如#000、rgb(0,0,0)），不是 Sass 变量名（如$gray-200）—— 否则contrast-color()计算失败，导致禁用态文字灰成一片 - 若需微调 hover 亮度，不要重写整个 mixin，改用
darken($value, 10%)或mix(#000, $value, 15%)作为第二参数传入 - 禁用态透明度由
$btn-disabled-opacity控制，修改它会影响所有按钮，建议只在局部覆盖：&:disabled { opacity: .65; }
编译后 CSS 体积暴增？警惕嵌套循环与冗余输出
每次 @each 都会为每个变体生成完整规则集（包括 :hover、:focus、:active、:disabled），5 个变体 = 至少 25 块样式块。优化方式：
- 只对真正需要的变体调用
@each，别把$theme-colors全量循环 —— 用子集map-keys($my-button-variants)提取键名再遍历 - 避免在
@each内部嵌套媒体查询，否则每种变体都复制一遍响应式规则 - 开发时用
/*rtl:begin:ignore*/注释跳过 RTL 编译（如果项目不用 RTL）
最易忽略的是：Sass 源码里删了某个变体，但 CSS 缓存没清，旧类名仍存在且无对应样式 —— 务必验证浏览器开发者工具中是否真有该 class 的声明块。
