bootstrap 5 的 bg-gradient 类不响应断点，需用媒体查询配合 background-image 实现断点渐变；自定义类须加 !important 覆盖默认样式，js 动态切换需节流并手动初始化。
bg-gradient类本身不响应断点，别指望加md:或d-md-block能控制渐变开关
Bootstrap 5 的 bg-gradient 和 bg-gradient-primary 等类是全局生效的纯 CSS 工具类，没有媒体查询包裹。写 bg-gradient-primary d-md-none 只会让整个元素消失，不是“中屏才启用渐变”——渐变逻辑本身没被断点约束。
常见错误包括：
- 以为
bg-gradient像d-md-block那样支持前缀，结果加了md:bg-gradient完全无效（Bootstrap 不识别这种写法） - 在 SCSS 中误设
$enable-gradients: false，导致所有渐变类静默失效，控制台无报错 - 只写
bg-gradient没配bg-primary等颜色类，它只是个“开关”，不带颜色也不定义方向
用媒体查询 + background-image 实现真正断点渐变
最直接可靠的做法：对目标容器写媒体查询，用 background-image 注入渐变，避免用 background 简写覆盖已有背景色。
示例：仅在 md 及以上显示左上→右下蓝紫渐变
@media (min-width: 768px) {
.hero-section {
background-image: linear-gradient(135deg, #0d6efd, #6f42c1);
}
}
关键点：
- 必须用
background-image，不是background—— 后者会清掉可能存在的background-color或图片纹理 - 方向优先用角度（如
135deg），比to right兼容性更稳；旧版 Safari 对to-r或left to right支持差 - 颜色至少两个，否则仍是纯色；移动端 Safari 对 color-stop 格式敏感，写
50% #000比50%, #000更稳妥 - 如果项目用 Sass，可复用 Bootstrap 断点变量：
@include media-breakpoint-up(md) { ... }
自定义带断点前缀的渐变类（适合多处复用）
若多个组件需相同断点逻辑，可定义类似 bg-md-gradient-primary 的类，避免重复写媒体查询。
SCSS 示例：
@include media-breakpoint-up(md) {
.bg-md-gradient-primary {
background-image: linear-gradient(135deg, $primary, $secondary) !important;
}
}
使用时注意顺序：<div class="bg-md-gradient-primary bg-light"> —— 自定义类在前，<code>bg-light 在后，确保小屏回退到纯色背景。
要点：
- 加
!important是必要的：Bootstrap 的bg-light等类自带!important，你的媒体查询规则需同等权重才能覆盖 - 别用
background简写，否则可能意外抹掉background-color，导致:disabled状态文字不可读 - 如果用了深色模式，记得额外加
@media (prefers-color-scheme: dark)分别适配
JS 动态切换渐变类（仅限需要实时响应的场景）
纯 CSS 媒体查询无法响应滚动、视口缩放等动态行为。若需根据窗口宽度频繁启停渐变，可用 JS 监听 resize 并切换类。
示例：
function updateGradientClass() {
const el = document.querySelector('.my-element');
if (window.matchMedia('(min-width: 768px)').matches) {
el.classList.add('bg-gradient-custom');
} else {
el.classList.remove('bg-gradient-custom');
}
}
window.addEventListener('resize', updateGradientClass);
updateGradientClass(); // 初始化执行一次
注意：
- 不要用
el.className = '...'全量重写，会丢掉其他必要 class（如container、py-5） - 用
classList.add()/classList.remove()更安全 - 首次加载必须手动调用一次
updateGradientClass()，否则页面初始状态可能错位 - 高频 resize 可考虑节流，但多数场景无需
