bootstrap 5 的 bg-gradient 类不支持断点渐变，因其源码未包含媒体查询；需在项目级 css 中手动用 @media 控制 background-image，并注意兼容性、权重及层级关系。
直接改 Bootstrap 源码无法实现断点渐变
Bootstrap 5 的 bg-gradient 类本身不带任何媒体查询，所有渐变工具类（如 bg-gradient-primary）都是全局生效的静态规则。你在 SCSS 源码里改 $enable-gradients 或重编译 CSS，依然不会生成带 @media 的响应式渐变类——这是设计使然，不是配置遗漏。
常见误操作包括：
- 在
_variables.scss里调大$grid-breakpoints，以为能“触发”断点渐变 —— 它只影响栅格和断点类（如d-md-none），不影响渐变工具类 - 给
bg-gradient手动加@include media-breakpoint-up(md)—— 编译后仍无断点包裹，因为官方源码没这么写，强行加会破坏工具类体系 - 删掉
bg-gradient的background-image声明，想“留空等 JS 注入” —— 结果是渐变彻底消失，且无 fallback 机制
真正要改的是你自己的 CSS，不是 Bootstrap 源码
响应式渐变必须由你主动用媒体查询控制 background-image，而不是指望 Bootstrap 提供带断点前缀的类。源码修改方向错了，精力该放在项目级样式上。
关键实操点：
- 基础态（小屏）先写
background-color，例如.hero { background-color: #fff; } - 再用
@media (min-width: 768px)（严格对齐 Bootstrap 的md断点）覆盖background-image - 方向用角度（如
90deg）而非to right，避免旧 Safari 兼容问题 - 颜色至少两个值，否则浏览器当纯色处理；移动端 Safari 对
50% #000格式比50%, #000更稳定
如果非要“扩展”Bootstrap 工具类，得自己补 SCSS
你可以新建一个 _custom-gradients.scss 文件，在里面定义类似 bg-md-gradient-to-r 的类，但要注意：
- 必须用
!important—— 因为 Bootstrap 的bg-light等类自带!important，你的规则权重不够会被盖掉 - 要用
@include media-breakpoint-up(md)而非硬编码768px，确保和 Bootstrap 断点变量同步 - 颜色推荐引用
$primary、$secondary变量，方便主题切换时自动更新 - 使用时 class 顺序很重要：
class="bg-md-gradient-to-r bg-white"，自定义类在前，保底色在后
容易被忽略的底层细节
渐变是 background-image，不是 background-color。哪怕你把 bg-gradient-primary 和 bg-white 写在同一元素上，后者也不会“覆盖”前者 —— 它们共存，只是 background-image 画在 background-color 上层。所以：
- 别用
background: #fff这种简写去覆盖，它会清掉background-image，导致渐变消失 - 子元素（如
.card）默认有白色背景，会完全遮住父容器渐变 —— 得手动设background-color: rgba(255,255,255,0.9)留透出空间 - 深色模式下，
prefers-color-scheme: dark必须单独写媒体查询重置渐变色，否则用户切暗色主题后看到的仍是亮色渐变
