<p>Bootstrap 5 的 bg-gradient 类不支持响应式断点，需用媒体查询配合 background-image 实现；必须搭配 bg-* 类使用，避免被子元素背景覆盖，并注意文字可读性与 fallback 背景设置。</p>
Bootstrap 5 的 bg-gradient 类根本不响应断点
别试 md:bg-gradient-primary 或 bg-gradient-primary d-md-none——前者是 Tailwind 写法，Bootstrap 完全不识别；后者只是把整个元素藏了，不是“渐变关闭”。bg-gradient 和 bg-primary 这类工具类都是无媒体查询的全局 CSS 规则，写在哪都生效，断点前缀对它无效。
常见误判现象：bg-gradient-primary 在小屏看着没效果，其实是被子元素（比如 .card、.container）的纯色背景盖住了，不是渐变没加载。
- 检查 computed styles：确认
background-image是否为none，是的话大概率被background: #fff这类简写覆盖了 - 确保没在 Sass 中设
$enable-gradients: false，否则所有渐变类静默失效，控制台零提示 -
bg-gradient单独用无效，必须搭配至少一个bg-*类（如bg-primary），它只提供渐变“开关”，不带颜色也不定义方向
用 @media 直接控制 background-image
最轻量、最可控的做法：对目标容器写媒体查询，只用 background-image 注入渐变，不碰 background 简写，避免清掉已有 background-color 或纹理。
示例：仅在 md 及以上（768px）启用左上→右下蓝紫渐变
@media (min-width: 768px) {
.hero-section {
background-image: linear-gradient(135deg, #0d6efd, #6f42c1);
}
}
- 断点值必须严格用
768px，和 Bootstrap 5 的md一致（不是767px或770px） - 方向优先写角度（如
135deg），比to right兼容性更稳；旧版 Safari 对to-r或left to right支持差 - 颜色至少两个，否则仍是纯色；移动端 Safari 对
50%, #000这种 color-stop 格式敏感，改用50% #000 - 基础态（小屏）样式必须写在媒体查询外，例如先写
.hero-section { background-color: #fff; }，否则大屏可能继承不到 fallback
自定义带断点前缀的渐变类（适合多处复用）
如果多个组件都要相同断点逻辑，可以定义类似 bg-md-gradient-primary 的类，避免重复写媒体查询。但要注意权重问题——Bootstrap 的 bg-light 等类自带 !important，你的自定义类也得加。
SCSS 示例（使用 Bootstrap 断点变量）：
@include media-breakpoint-up(md) {
.bg-md-gradient-primary {
background-image: linear-gradient(135deg, #0d6efd, #86b7fe) !important;
}
}
- HTML 中使用顺序很重要：
<div class="bg-md-gradient-primary bg-light">—— 自定义类在前，bg-light在后，确保小屏回退到纯色背景 - 必须用
background-image，不是background；后者会抹掉background-color，导致小屏 fallback 失效 - 别指望靠
d-none d-md-block套两层来模拟断点渐变，布局易错、语义混乱，且无法处理渐变与子元素背景的叠加关系
渐变背景下的文字可读性容易被忽略
原生 Bootstrap 的文字色（如 text-dark、text-white）是按纯色背景设计的。换成浅色渐变后，对比度常跌破 WCAG 4.5:1 标准，阳光直射屏幕时几乎不可读。
- 必须同步调整：
color（比如浅渐变配text-dark，深渐变配text-white）、border-color（加一道实色边框能立刻提升辨识度） - 用 WebAIM Contrast Checker 这类工具校验，别凭肉眼判断
- 渐变方向、alpha 值、色标位置三者稍一变动，文字可读性就可能断崖式下跌——这没法靠规则自动修复，得手动调、反复测
- 如果容器里有
.card或显式设置了background-color: white的子元素，它们会完全盖住底层渐变；解决办法不是调z-index（没定位时无效），而是把子元素背景改成rgba(255, 255, 255, 0.9)留点透出空间
