bootstrap 5 的 bg-gradient 类不支持断点前缀，需用 @media 手动控制渐变启用；md:bg-gradient-primary 是 tailwind 写法，bootstrap 不识别；bg-gradient-primary 与 display 无关，关闭渐变须显式覆盖 background-image。
bg-gradient 类在 Bootstrap 5 中不支持断点前缀，也没有“按需加载”机制——它一旦存在，就在所有屏幕尺寸下生效。所谓“按需”，实际是「按断点条件性启用渐变样式」，必须绕过工具类，用 CSS 层叠逻辑手动控制。
为什么 md:bg-gradient-primary 或 bg-gradient-primary d-md-block 不行
md:bg-gradient-primary 或 bg-gradient-primary d-md-block 不行这是最常踩的坑：md:bg-gradient-primary 是 Tailwind 的写法，Bootstrap 5 完全不识别，浏览器直接忽略该规则；而 bg-gradient-primary d-md-block 只是让元素在小屏时 display: none，不是“关闭渐变”，而是“整个区块消失”。你真正要的是渐变本身只在目标断点渲染，其他时候退回到纯色背景。
-
bg-gradient-primary底层是background-image: linear-gradient(135deg, ...)，它和display无关，也不会因断点类自动开关 - 如果同时加了
bg-white和bg-gradient-primary，后者会覆盖前者，但小屏下你仍看到渐变——除非你显式把它关掉 - 误设
$enable-gradients: false在 Sass 中会导致所有渐变静默失效，控制台无提示，极难排查
用 @media 精确控制渐变启用断点
@media 精确控制渐变启用断点这是最轻量、兼容性最好、也最符合 Bootstrap 5 设计意图的做法：基础态（小屏）写默认背景色，大屏用媒体查询覆盖 background-image。
- 断点值必须严格对齐 Bootstrap 5 定义：
@media (min-width: 768px)对应md，不能写767px或770px - 只改
background-image，不要用background简写——否则会清掉background-color，导致小屏 fallback 失效 - 方向优先用角度（如
90deg表示从左到右），比to right在旧版 Safari 中更稳 - 颜色至少两个色值，否则仍是纯色；移动端 Safari 对
50%, #000这种 color-stop 格式敏感，建议写成50% #000
.hero-section {
background-color: #fff;
}
@media (min-width: 768px) {
.hero-section {
background-image: linear-gradient(90deg, #0d6efd, #20c997);
}
}
自定义带断点前缀的渐变类（适合多处复用）
如果你在多个组件中都需要 “仅在 lg 启用垂直渐变”，可以封装一个类，比如 bg-lg-gradient-to-b。注意：这不是 Bootstrap 原生类，必须手动补全，且权重要足够高。
- 必须加
!important：因为 Bootstrap 的bg-light等类自带!important，你的规则需同等权重才能覆盖 - 用 Sass 时推荐复用断点变量：
@include media-breakpoint-up(lg)，避免硬编码像素值 - 颜色建议引用 Bootstrap 调色板变量（如
$primary,$success），便于主题同步 - 使用时注意 class 顺序：
class="bg-lg-gradient-to-b bg-white"——自定义类在前，降级纯色在后
@include media-breakpoint-up(lg) {
.bg-lg-gradient-to-b {
background-image: linear-gradient(180deg, $primary, $success) !important;
}
}
深色模式 + 断点渐变容易被忽略的关键点
很多人只做了断点控制，却忘了深色模式下渐变颜色可能完全不可读。例如 bg-gradient-primary 在暗背景下依然用亮蓝色系，文字对比度暴跌。
- 不能靠断点类解决，得额外加
@media (prefers-color-scheme: dark)重写渐变值 - 若用了自定义类（如
bg-md-gradient-primary），深色模式适配也要单独写，不能复用同一套色值 - 检查 computed styles 时，确认
background-image在深色模式下是否真的被新规则命中——浏览器 devtools 有时不会实时刷新媒体查询匹配状态
复杂点不在写法，而在叠加逻辑：断点、深色模式、子元素遮挡、Sass 变量开关，四者任意漏掉一个，渐变就可能“看似生效实则隐身”。
