bg-gradient类本身不响应断点，需配合bg-*类及媒体查询实现响应式渐变；常见失效原因包括背景覆盖、$enable-gradients禁用、无高度、透明色覆盖及Safari兼容问题。
bg-gradient 类本身不响应断点
Bootstrap 5 的 bg-gradient 及其衍生类（如 bg-gradient-primary）是静态 CSS 规则，内部没有包裹任何 @media 查询。它在所有断点下都生效——所谓“小屏不生效”，其实是你没看到，不是它没加载。
常见错觉来源：
- 子元素（比如
.card、.container）自带纯色背景，盖住了父容器的渐变 - 小屏时你写了
background-color: #fff或用了bg-light，而background-color会压在background-image下方，完全遮蔽渐变 - 检查浏览器开发者工具的 Computed 面板，如果
background-image显示为none，大概率是被background: #fff这类简写覆盖了
渐变依赖 bg-* 颜色类才能触发
bg-gradient 不是独立功能，它只是个“开关”。必须搭配至少一个 bg-* 类（如 bg-primary）才会由 Bootstrap 注入 background-image: linear-gradient()。单独写 bg-gradient，CSS 规则里压根不会生成渐变声明。
容易漏掉的条件：
- 项目 SCSS 中设了
$enable-gradients: false→ 所有渐变类静默失效，控制台无报错 - 元素没有高度（例如空
<div></div>），得加min-height或内容撑开 - 用了
bg-transparent或行内style="background-color: transparent"，导致 fallback 色缺失，渐变又没触发，结果就是空白
移动端 Safari 对 color-stop 格式敏感
渐变写法看似简单，但移动端 Safari（尤其 iOS 15–16）对 linear-gradient() 的 color-stop 解析很挑。写成 50%, #000 容易被忽略，变成单色；改用 50% #000 才稳定。
其他兼容性要点：
- 方向优先用角度（如
135deg），比to right更可靠；旧版 Safari 不认缩写to-r - 颜色至少两个，否则仍是纯色背景
- 别用
background: linear-gradient(...)简写——它会清掉已有的background-color或纹理，小屏回退直接失效
真正可控的响应式渐变只能靠 @media + background-image
想让渐变“只在 md 及以上生效”，唯一靠谱做法是绕过 bg-gradient 工具类，手动写媒体查询：
.hero-section {
background-color: #fff;
}
@media (min-width: 768px) {
.hero-section {
background-image: linear-gradient(135deg, #0d6efd, #6f42c1);
}
}关键细节：
- 断点值必须严格用
768px，和 Bootstrap 5 的md断点一致（不是 767px 或 770px） - 基础态（小屏）样式必须写在媒体查询外，否则大屏可能继承不到 fallback
- 自定义类如
.bg-md-gradient-primary若需复用，得加!important—— 因为bg-light等类自带!important，你的规则权重不够会失效
小屏渐变“不生效”最常被当成样式 bug，其实多数是 fallback 逻辑缺失或层叠顺序混乱。重点不是怎么让渐变出现，而是怎么让它在不同断点下有明确的视觉退路：纯色 → 渐变 → （必要时）深色模式重写。
