bg-gradient单独使用无效，因它仅是渐变“开关”，必须搭配bg-*颜色类（如bg-primary）才能由Bootstrap注入background-image: linear-gradient()；漏颜色类、禁用渐变配置、元素无高度或被其他样式覆盖均会导致失效。直接用
bg-gradient 类最省事，但必须和 bg-* 颜色类（如 bg-primary）一起用，单独写 bg-gradient 无效。
为什么加了 bg-gradient 却没渐变？
因为 bg-gradient 本身只是个“开关”，不带颜色、不定义方向。它只在搭配至少一个 bg-* 类（比如 bg-info）时，才由 bootstrap 自动注入 background-image: linear-gradient()。常见失效原因包括：
- 只写了
bg-gradient，漏掉bg-primary这类颜色类 - 项目引入的是精简版 CSS，或 SCSS 中关掉了
$enable-gradients: false - 元素没有高度（比如空
<div>），得加min-height或内容撑开 - 被
style="background-color: #fff"、bg-transparent或其他!important规则覆盖
bg-gradient-to-r 在 Bootstrap 5 里根本不存在
Bootstrap 5 原生不支持 Tailwind 风格的 bg-gradient-to-r、bg-gradient-to-b 这类方向类。它的预设渐变类（如 bg-gradient-primary）方向固定为 135deg（左上→右下），不是从左到右，也不是从上到下。
如果真要水平渐变，必须手写：
.my-horiz {
background-image: linear-gradient(to right, #0d6efd, #86b7fe) !important;
}
注意：to right 比 to-r 或 left to right 更可靠；颜色至少两个，否则还是纯色。
自定义渐变时，background 和 background-image 怎么选？
优先用 background-image，尤其对按钮、警示框、进度条这类组件——Bootstrap 默认就是靠它实现渐变的，直接覆盖更稳妥，不会意外清掉 background-color 导致 :disabled 状态变白。
实操要点：
- 必须加
!important：Bootstrap 的 CSS 权重高，不加大概率被忽略 - 搭配
background-color: transparent !important作保底，避免 fallback 失效 - 别用
background: linear-gradient()简写：它会一并重置background-image和background-color，容易破坏组件原有状态逻辑（比如按钮的:hover遮罩） - 移动端 Safari 对
color-stop语法敏感（如50%, #000），推荐用标准写法50% #000
渐变背景下的文字和边框经常看不清
原生 Bootstrap 的文字色（如 .alert-warning 的 #856404）是按纯色背景设计的。换成浅色渐变后，对比度常跌破 4.5:1，阳光直射屏幕时几乎不可读。
必须同步调整：
-
color：比如浅渐变配text-dark，深渐变配text-white -
border-color：加一道实色边框（如border: 1px solid #ffc107）能立刻提升辨识度 - 用工具校验对比度（如 WebAIM Contrast Checker），别凭肉眼判断
复杂点在于：渐变方向、alpha 值、色标位置三者稍一变动，文字可读性就可能断崖式下跌——这没法靠工具自动修复，得手动调、反复测。
