bg-gradient类不响应断点，必须用@media (min-width: 768px)显式控制background-image；需先设基础态样式，用linear-gradient(135deg)、至少两色、50% #000格式，并注意子元素遮挡与透明度调整。
bg-gradient类本身不响应断点，加md:前缀完全无效
Bootstrap 5 的 bg-gradient 和 bg-gradient-primary 是纯静态工具类，CSS 规则里没有媒体查询包裹。你写 md:bg-gradient-primary 或 bg-gradient-primary d-md-block，前者会被浏览器忽略（Bootstrap 不识别 Tailwind 风格前缀），后者只是让元素在小屏消失——不是“渐变关闭”，而是整个区块没了。
常见错误包括：
- 以为加了
d-none d-md-block就能条件启用渐变，结果小屏时内容直接不可见 - 在 SCSS 中误设
$enable-gradients: false，导致所有渐变类静默失效，控制台无报错 - 只写
bg-gradient没配bg-primary等颜色类，它只是个开关，不带颜色也不定义方向
@media (min-width: 768px) 是唯一可靠方案
必须用媒体查询显式控制 background-image，且断点值严格对齐 Bootstrap 5 的 md：768px（不是 767px 或 770px）。
关键点：
- 基础态（小屏）样式必须写在媒体查询外，例如先设
.hero-section { background-color: #fff; } - 务必用
background-image: linear-gradient(...)，不是background: linear-gradient(...)—— 后者会清掉已有的background-color或纹理图 - 方向优先用角度（如
135deg），比to right兼容性更稳；旧版 Safari 对to-r或left to right支持差 - 颜色至少两个，否则仍是纯色；移动端 Safari 对
color-stop格式敏感，写50% #000比50%, #000更稳妥
自定义带断点前缀的类适合多处复用
如果多个组件需相同逻辑（比如所有 .card 在 md+ 显示蓝紫渐变），可在项目 SCSS 或全局 CSS 中定义类似 bg-md-gradient-primary 的类：
@include media-breakpoint-up(md) {
.bg-md-gradient-primary {
background-image: linear-gradient(135deg, #0d6efd, #6f42c1) !important;
}
}
使用时注意顺序：<div class="bg-md-gradient-primary bg-light"> —— 自定义类在前，<code>bg-light 在后，确保小屏回退到纯色背景。
要点：
-
!important是必要的：Bootstrap 的bg-light等类自带!important，你的规则需同等权重才能覆盖 - 若用原生 CSS 而非 Sass，直接写
@media (min-width: 768px) { ... }即可 - 别试图重写
@media (max-width: 767.98px) { .bg-primary { ... } }—— Bootstrap 的.bg-primary规则权重高且无媒体查询，你的规则会被忽略
渐变生效但看不见？大概率是子元素盖住了
渐变背景没显示出来，90% 不是写错了，而是被子元素遮挡：
- 子元素（如
.card、.btn）显式设置了不透明背景色，改成background-color: rgba(255, 255, 255, 0.9)留点透出空间 - 误把渐变写在
.row上，而.row默认有负外边距，实际渲染区域比容器小 - 用了
overflow: hidden且子元素超出，导致渐变被裁掉（尤其圆角 + 渐变组合时） - 文字或边框在浅色渐变上对比度不足，需同步调整
color和border-color，别凭肉眼判断
复杂点在于：渐变方向、alpha 值、色标位置三者稍一变动，文字可读性就可能断崖式下跌——这没法靠工具自动修复，得手动调、反复测。
