bootstrap 5 的 bg-gradient-* 类无法满足自定义需求，因其方向固定为135deg、仅支持内置主题色、不支持角度调节或颜色停点扩展，且无响应式变体；自定义渐变必须手写 css 或通过 sass 扩展 utilities 实现。
Bootstrap 5 没有现成的 text-gradient 或 bg-gradient-custom 工具类，所有渐变效果都得靠自定义 CSS 实现；直接加 bg-gradient-primary 只能用内置主题色，且无法控制方向或颜色停点。
为什么 bg-gradient-* 类不能满足自定义需求
Bootstrap 5 的渐变工具类（如 bg-gradient-primary）本质是组合开关：它只启用预设的 background-image: linear-gradient(to bottom, var(--bs-primary), var(--bs-primary-emphasis))，方向固定为垂直、颜色来自 $theme-colors、不支持角度或双色以外的配置。你没法通过加 bg-gradient-to-r 或 bg-gradient-135deg 来改方向——这类 Tailwind 风格类根本不存在。
-
bg-gradient单独写无效，必须配对如bg-gradient-primary - 没有响应式渐变类（如
sm:bg-gradient-success），Sass 编译时不生成 - 若同时用了
bg-primary和bg-gradient-primary，后者会覆盖前者，但底层色逻辑被破坏，渐变可能发灰或不显
给文字加渐变必须清掉所有 .text-* 类
Bootstrap 的 .text-primary 等类会硬设 color，直接盖掉 background-clip: text 效果。想让文字本身渐变，第一步不是写 CSS，而是删 HTML 中所有 text-* 类。
- 必须显式写
color: transparent，不能留空或依赖继承 -
-webkit-background-clip: text是硬性前缀，Safari 15.6–16.4 不加就完全失效 - 元素需是内联级，
<div> 要加 <code>display: inline或inline-block，否则剪辑区域错位 - 别在
<button></button>上强套，按钮默认有border、padding、box-shadow，容易裁不齐 - 自定义 utility 默认不带
!important，而.btn .text这类选择器权重更高，必须显式加rules: "background-image !important" - 若只要非响应式版本，设
responsive: false，否则sm:bg-gradient-horiz会无意义生成 - 颜色值别硬编码，用
map-get($theme-colors, primary)保持主题一致性 - 编译后要清缓存，否则旧 CSS 文件里仍没新类
-
style="background-image: linear-gradient(135deg, #0d6efd, #6f42c1); background-color: transparent;"——background-color: transparent是关键，否则!important背景色会遮住渐变 -
:hover里必须重写整条background-image，不能只改颜色；iOS Safari 可能跳过:active，得显式写 - 禁用点击高亮：
-webkit-tap-highlight-color: transparent，否则安卓上蒙层盖住渐变 - 禁用态（
:disabled）不能只靠opacity: 0.7，要同步降渐变色对比度，否则文字可读性崩塌
如何安全扩展 utilities 实现可复用的渐变类
想让 bg-gradient-horiz 或 text-gradient-purple 成为真正的工具类，必须进 Sass 编译流程，改 $utilities map；仅写 CSS 规则不会生成响应式变体，也不会带 !important 权重，在 <button></button> 里大概率被压住。
最简可行方案：内联样式 + 手动状态管理
如果项目没 Sass 构建环境，或只需局部用，直接用 style 属性是最稳的 fallback。但要注意：所有交互态（:hover、:active）必须单独声明，Bootstrap 不会帮你继承渐变。
真正卡住人的从来不是“怎么写渐变”，而是忘了 background-color: transparent 这一行，或者以为加了 bg-gradient-primary 就万事大吉——结果在按钮里、悬停时、禁用状态下全失效。这些地方没有魔法，只有显式覆盖和状态穷举。
