bootstrap 5 的 bg-gradient 类不支持断点前缀，因其渐变工具类是全局静态 css，无媒体查询逻辑；必须用 @media 手动控制 background-image 并显式设置小屏 fallback 背景色。
不能直接用 bg-gradient 类加断点前缀（比如 md:bg-gradient-primary），它压根不生效——Bootstrap 5 的渐变工具类是全局 CSS，没有媒体查询逻辑。
为什么 bg-gradient + 断点类完全无效
Bootstrap 的 bg-gradient-primary 这类类名是静态声明，编译后就是一段无条件的 background-image: linear-gradient(...)；d-md-block 或 text-lg-center 这些断点类只控制 display、text-align 等属性，对 background-image 零影响。你写 bg-gradient-primary d-sm-none d-md-block，结果只是小屏整个容器被隐藏，不是“渐变关闭”。
常见误判还包括：bg-gradient 单独使用也不起作用——它必须和至少一个 bg-* 类（如 bg-primary）配对，否则没颜色基础，渐变无从生成。
- 检查是否在 Sass 中设了
$enable-gradients: false：所有渐变类会静默失效，控制台不报错 - 确认 computed styles 中
background-image是否为none：大概率是某处background: #fff这类简写覆盖掉了它 - 别信“小屏没效果”——更可能是子元素（比如
.card、.row）的纯色背景盖住了容器渐变
用 @media 手动控制 background-image 最可靠
直接给容器写媒体查询，只操作 background-image，不碰 background 简写，避免清掉已有 background-color 或纹理。小屏 fallback 必须显式声明纯色背景。
示例：仅在 md（≥768px）及以上启用左上→右下蓝紫渐变，小屏回退为白色：
.hero-section {
background-color: #fff;
}
@media (min-width: 768px) {
.hero-section {
background-image: linear-gradient(135deg, #0d6efd, #6f42c1);
}
}
- 断点值必须严格用
768px，和 Bootstrap 5 的md定义一致（不是 767px 或 770px） - 方向优先写角度（如
135deg），比to right兼容性更稳；旧版 Safari 对to语法支持差 - 颜色至少两个，否则仍是纯色；移动端 Safari 对
50%, #000这种 color-stop 格式敏感，改用50% #000 - 基础态（小屏）样式必须写在媒体查询外，否则大屏可能继承不到 fallback
渐变没显示？先查子元素是否“盖住”了它
渐变背景不出现，90% 不是 CSS 写错了，而是子元素的背景色把底层盖死了。尤其当容器里用了 .card、.bg-white 或显式写了 background-color: white 的组件时，整个视觉上就看不到渐变。
- 不要调高容器的
z-index：它没定位，z-index无效 - 检查子元素是否显式设置了不透明背景色 —— 改成
background-color: rgba(255, 255, 255, 0.9)留点透出空间 - 是否误把渐变写在了
.row上？.row默认有负外边距，实际渲染区域比容器小 - 是否用了
overflow: hidden且子元素超出？导致渐变被裁
多个地方要用相同断点渐变？自定义带前缀的类
如果项目中多处需要“仅 md+ 显示渐变”，可以定义类似 bg-md-gradient-primary 的类，避免重复写媒体查询。注意权重问题：Bootstrap 的 bg-light 等类自带 !important，你的自定义类也得加。
Sass 示例（使用 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"> —— 顺序很重要，先自定义类，再 fallback 色类 <li>别用 <code>background简写注入渐变，否则会意外清掉已有的background-color或background-position - 如果项目没用 Sass，就老实用纯 CSS 媒体查询，别试图用 JS 动态切换类——除非真要配合滚动或视口进入等复杂交互
最易被忽略的是：渐变本身不触发重排，但文字对比度会随屏幕尺寸、环境光、字体缩放剧烈变化。同一组蓝紫渐变，在 sm 屏上配 text-dark 刚好可读，到了 xl 屏可能因字体相对变小立刻变灰蒙蒙——这事没法靠 CSS 自动适配，得实机测。
