因为bg-gradient只是无样式的“开关”，必须与bg-gradient-primary等12种内置颜色类配对使用才生效；单独使用、方向错误、高度为0、或混用bg-primary均会导致失效。
为什么加了 bg-gradient 却没效果
因为 bg-gradient 本身不带颜色、不带方向、不触发任何样式——它只是个“开关”，必须和具体颜色类配对使用才生效。单独写 class="bg-gradient" 等于没写。
常见错误包括：
- 只加
bg-gradient，没加bg-primary或bg-gradient-primary - 误以为 Bootstrap 5 支持
bg-gradient-to-r这类 Tailwind 风格写法（实际不支持） - 项目引入的是精简版 CSS 或自定义编译时关掉了
$enable-gradients: false，导致所有渐变类静默失效 - 元素没有内容或未设
height/min-height，高度为 0，渐变自然不可见
bg-gradient-primary 和 bg-gradient + bg-primary 的区别
二者效果完全不同，且后者是错的用法。
bg-gradient-primary 是 Bootstrap 5.3+ 内置的完整渐变类，底层是 background-image: linear-gradient(135deg, #0d6efd, #86b7fe)；而 bg-gradient bg-primary 是把两个独立类叠加：bg-gradient 无样式，bg-primary 只设 background-color，最终只有纯色，没有渐变。
正确组合方式只有这一种：
bg-gradient-primarybg-gradient-successbg-gradient-dark- ……共 12 种内置主题色，不支持
bg-gradient-purple这类非标准名（除非你扩展 SCSS 变量并重编译）
渐变方向怎么控制？能水平或垂直吗
Bootstrap 5 默认所有 bg-gradient-* 类都是 135deg 对角渐变（左上 → 右下），不提供类名切换方向。所谓“垂直渐变”“水平渐变”只能手写 CSS 实现。
例如要从上到下垂直渐变：
.bg-gradient-vertical {
background-image: linear-gradient(to bottom, #0d6efd, #6f42c1) !important;
}
注意点：
- 别用
background: linear-gradient(...)简写，它会清掉background-color，影响降级表现 - 如果同时用了
bg-gradient-primary和自定义类，后者需加!important才能覆盖前者（因 Bootstrap 默认带!important） - 移动端 Safari 中，
to bottom比0deg更可靠，避免渲染抖动
文字颜色怎么配才不糊？别乱用 text-white
渐变背景上直接套 text-white 看似稳妥，但遇到浅色渐变段（比如 bg-gradient-warning 的右半部分）可能对比度不足，尤其小字号时过不了 WCAG AA 标准。
更靠谱的做法：
- 优先用
text-bg-primary这类语义化反色类——它会自动计算可读性足够的前景色 - 深色渐变（如
bg-gradient-dark）配text-light，比text-white更柔和 - 避免在同一个元素上既写
bg-gradient-success又写text-success：前者是蓝绿渐变，后者是固定绿色文字，视觉冲突 - 检查 computed styles 中
color值是否被父级color继承覆盖——渐变背景不改变文字继承链
最易被忽略的一点：text-bg-* 类依赖 Bootstrap 的颜色系统变量，如果你改过 $theme-colors 却没同步更新 $theme-color-interval，深色模式下反色计算就会失准。
