<p>Bootstrap 5 不支持 bg-gradient-md 等带断点前缀的渐变类，它们是 Tailwind 语法；所有内置 bg-gradient-* 类均为全局固定 135deg 方向；可靠方案是手动写 @media (min-width: 768px) 并仅修改 background-image。</p>
直接用 bg-gradient-md 这类类名会失效
Bootstrap 5 官方 CSS 中根本不存在 bg-gradient-md、md:bg-gradient-to-r 这类带断点前缀的渐变类——它们是 Tailwind 的语法，浏览器解析时会完全忽略。所有内置 bg-gradient-* 类（如 bg-gradient-primary）都是无媒体查询的全局规则，方向固定为 135deg，且在所有屏幕尺寸下同时生效。
常见误操作包括：
-
bg-gradient-primary d-none d-md-block：小屏时整个元素消失，不是“渐变关闭”，而是内容不可见 -
bg-gradient-primary d-md-none：大屏时元素被隐藏，渐变依然存在但不可见 - 单独写
bg-gradient：它只是个开关，不带颜色也不定义方向，必须搭配bg-primary等才有效
@media (min-width: 768px) 是唯一可靠方案
真正可控的做法，是绕过工具类，对目标容器手动写媒体查询，并只修改 background-image。这是最轻量、兼容性最好、也最容易调试的方式。
关键约束条件：
- 断点值必须严格等于 Bootstrap 5 的
md：即@media (min-width: 768px)，不是767px或770px - 必须用
background-image，不能用background或background-color—— 后者会覆盖掉已有背景色或纹理 - 小屏基础态（fallback）必须写在媒体查询外，例如先设
.hero { background-color: #fff; } - 方向优先写角度，如
90deg（左→右）、180deg（上→下），比to right在旧版 Safari 中更稳
示例：仅在 md 及以上启用蓝→青渐变，小屏回退纯白
.hero {
background-color: #fff;
}
@media (min-width: 768px) {
.hero {
background-image: linear-gradient(90deg, #0d6efd, #20c997);
}
}
自定义带断点前缀的渐变类要注意权重和顺序
如果多个组件都要“仅在 lg 启用垂直渐变”，可以封装成 bg-lg-gradient-to-b 这类自定义类，但需注意它不是 Bootstrap 原生类，必须手动补全，且容易踩坑。
实操要点：
- 必须加
!important：因为 Bootstrap 的bg-light等类自带!important，你的规则权重不够会被覆盖 - SCSS 中推荐复用断点变量：
@include media-breakpoint-up(lg)，避免硬编码像素值 - 颜色建议引用 Bootstrap 调色板变量（如
$primary、$success），便于主题同步 - 使用时 class 顺序很重要：
class="bg-lg-gradient-to-b bg-white"，自定义类在前，保底色类在后
别忘了子元素遮挡和可访问性断裂
渐变背景常被忽略的两个实际问题：一是子元素（比如 .card、.container）默认有纯白背景，会完全盖住父级渐变；二是文字对比度在渐变上极易跌破 WCAG 4.5:1 标准。
应对方式：
- 子元素若需透出背景，改用
background-color: rgba(255, 255, 255, 0.9)，而不是background-color: #fff - 深色模式需额外适配：
@media (prefers-color-scheme: dark)下重写渐变色值，否则用户切深色主题后仍看到亮色渐变 - 文字色必须同步调整：深渐变配
text-white，浅渐变配text-dark，不能依赖默认继承
真正难的不是写对媒体查询，而是让渐变在各种组合场景下都“看得清、不遮挡、不突兀”。这些细节往往要等真机测试时才暴露。
