Bootstrap 5+ 的 bg-gradient 必须与 bg-* 类组合使用才能生效，单独使用无效；若渐变不显示，需检查是否被 background-color、bg-transparent 或 !important 覆盖；自定义渐变应手动写 background-image 并加 !important；深色模式下需额外适配。
直接用 bg-gradient 类最省事，但得避开默认覆盖陷阱
Bootstrap 5+ 内置的 bg-gradient 是个开关类，它本身不指定方向或颜色，只启用渐变渲染逻辑。真正生效靠的是和 bg-* 类组合使用（比如 bg-primary bg-gradient），此时框架会自动注入 background-image: linear-gradient(...)。
常见错误是单独写 bg-gradient 没效果——它必须搭配一个带色值的背景类；或者写了 bg-primary bg-gradient 却发现还是纯色——那大概率是该元素被其他 CSS 强制设了 background-color，而 Bootstrap 的渐变声明优先级高于纯色，但低于 !important 或内联样式。
- 确保没在 JS 或 HTML 中用
style="background-color: ..."覆盖 - 检查是否误加了
bg-transparent，它会清掉整个背景（包括渐变） - 如果想自定义方向，得自己写 CSS，
bg-gradient不支持参数
background-image: linear-gradient() 手动覆盖更可控
当内置组合不够用（比如要垂直渐变、三色过渡、或用非主题色），就得绕过 bg-gradient，直接写 CSS。
关键点在于：Bootstrap 5 的 .progress-bar、.btn 等组件默认带 background-image，所以你只需替换它，而不是加 background-color——后者会被无视。
- 写法示例：
background-image: linear-gradient(to bottom, #4dabf7, #228be6); - 务必加
!important，否则容易被框架高权重要素压住 - 若用于按钮，注意文字颜色是否还够对比度；渐变底色暗时，
text-white可能比text-dark更稳妥
渐变 vs 纯色：性能差不多，但维护成本差很多
渲染性能上，现代浏览器对 linear-gradient 和 background-color 几乎无差别，别为这个纠结。
真正影响开发体验的是维护路径：
- 用
bg-primary bg-gradient：换主题时自动跟着$primary变，但颜色组合固定，无法微调停靠点 - 手写
background-image：完全自由，但一旦改品牌色，所有手动写的渐变都得逐个更新 - 混合风险：比如
bg-primary bg-gradient bg-opacity-75—— Bootstrap 5.2+ 才支持透明度叠加，老版本会直接失效
深色模式下渐变容易“消失”，因为没配变量
Bootstrap 5 的 --bs-gradient 等 CSS 变量默认不响应 data-bs-theme="dark" 切换。也就是说，你在 light 模式下写的 bg-primary bg-gradient，切到 dark 模式后，渐变颜色还是按 light 主题算出来的，可能和背景融成一片。
真要适配深色模式，得自己定义两套变量并用媒体查询切换，或者干脆放弃 bg-gradient，改用 background-image 配合 @media (prefers-color-scheme: dark) 块重写。
这一步多数人会跳过，直到 QA 在深色模式截图里发现进度条看不见才回头补。
