bootstrap 5的bg-gradient-*类必须与颜色主题类（如bg-primary）配对使用才生效，单独写bg-gradient无效；其方向固定为135deg，不支持to-r等方向类，需手写css实现水平渐变。
Bootstrap 5 的 bg-gradient-* 类不能单独用，必须配对颜色主题类（如 bg-primary）或直接用内置渐变类（如 bg-gradient-primary），否则不生效——这是最常卡住人的地方。
为什么加了 bg-gradient 却没渐变？
因为 bg-gradient 本身只是个“开关”，它不带任何颜色定义，也不控制方向。Bootstrap 5.3+ 中它只在和 bg-primary、bg-success 等组合时才触发渐变逻辑（前提是 $enable-gradients: true 已启用）。常见失效原因：
- 只写了
bg-gradient，没加任何颜色类（比如漏掉bg-primary） - 项目引入的是精简版 CSS，或自定义 SCSS 中关掉了
$enable-gradients - 元素没有高度：空
<div> 默认高为 0，渐变自然不可见，得加 <code>min-height或内容撑开 - 父容器有
background-color且层级更高，把子元素渐变盖住了 - 想水平渐变？只能手写 CSS：
background-image: linear-gradient(to right, #0d6efd, #86b7fe) -
bg-gradient-primary这类共 12 种，对应内置主题色，不支持bg-gradient-purple这种写法（除非你扩展 SCSS 变量并重编译） - 别混用
bg-primary和bg-gradient-primary：后者会完全覆盖前者，且两者逻辑冲突，可能让底层色计算出错 - 写
background: linear-gradient(...)有可能被 Bootstrap 的background-color简写覆盖（尤其 v4.x） - 用
background-image时，建议同时设background-color: transparent !important，保底兼容 - 务必加
!important：Bootstrap 的权重高，不加大概率被忽略 - 移动端 Safari 对
color-stop(50%, #000)解析有 bug（iOS 15.4 之前），推荐用标准语法50% #000 - 必须同步调整
color和border-color，不能只改背景 - 推荐用
text-white搭配深色系渐变（如bg-gradient-dark），用text-dark搭配浅色系（如bg-gradient-warning） - 边框别省略：加一道实色边框（如
border: 1px solid #ffc107）能立刻提升边缘辨识度 - 检查 computed styles 里
background-image是否为none——是的话，大概率被background: #fff这类简写干掉了
bg-gradient-primary 和 bg-gradient-to-r 不是一套体系
Bootstrap 5 原生不支持 Tailwind 风格的 bg-gradient-to-r 这类方向类。它的渐变方向是写死在类里的：bg-gradient-primary 默认是 135deg（左上→右下），不是从左到右也不是从上到下。
自定义渐变时，background 和 background-image 怎么选？
优先用 background-image，尤其在按钮、进度条、警示框这类组件上——因为 Bootstrap 默认就是靠 background-image: linear-gradient() 实现渐变的，直接覆盖它更稳妥，不会意外清掉 background-color 导致 :disabled 状态变白。
渐变背景下的文字和边框容易看不清
原生 Bootstrap 文字色（如 .alert-warning 的 #856404）是按纯色背景设计的，换成浅色渐变后对比度常跌破 4.5:1，尤其阳光直射屏幕时几乎不可读。
真正麻烦的从来不是写几行渐变代码，而是搞清哪一层样式在起效、哪个 !important 覆盖了你的意图、以及 iOS 上那个藏得极深的 color-stop 解析 bug。
