不能靠bg-gradient工具类实现响应式渐变，必须用@media手动控制background-image；需搭配fallback背景色、子元素透明度及深色模式适配，否则渐变不可见或对比度不达标。
不能靠 bg-gradient 工具类直接实现“响应式渐变”，因为 Bootstrap 的所有渐变类（如 bg-gradient-primary）都是全局生效、无断点逻辑的；真要让渐变只在特定断点出现，必须用 @media 控制 background-image。
为什么 bg-gradient-primary d-md-block 不等于“仅 md+ 渐变”
这个组合只是让元素在小屏隐藏、大屏显示，但渐变本身仍存在于 DOM 中——小屏时你看到的是空白，不是回退到纯色背景。更关键的是：bg-gradient-primary 依赖 background-image，而它不随断点变化；d-md-block 控制的是 display，两者根本不作用于同一渲染层。
-
bg-gradient-*类必须搭配至少一个bg-*类（如bg-light）才生效，否则只渲染后一个纯色 - 若项目 SCSS 中设了
$enable-gradients: false，所有渐变类会静默失效，控制台无提示 - 工具类方向只支持缩写（如
to-r），不支持to right或角度值，灵活性极低
用 @media 手动控制 background-image 最可靠
这是唯一能真正让渐变“按需启用”的方式，且兼容性好、权重可控、不污染 HTML 结构。
- 基础态（小屏）先写
background-color: #fff，确保降级可用 - 中屏起用
@media (min-width: 768px)（严格匹配 Bootstrap 5 的md断点），只覆盖background-image - 务必用
background-image: linear-gradient(135deg, #0d6efd, #6f42c1)，不用background简写，避免清掉已有背景色或纹理 - 颜色至少两个，单色值会被浏览器当纯色处理；移动端 Safari 对
50% #000比50%, #000更友好
渐变被子元素盖住？先查 background-color 而不是 z-index
容器加了渐变却看不见，90% 是因为子元素（比如 .card、.btn 或带 background: white 的 div）显式设置了不透明背景色，把底层渐变完全遮住了。
-
z-index对无定位元素无效，别浪费时间调它 - 把子元素的
background-color改成rgba(255, 255, 255, 0.9)，留出透出空间 - 检查是否误把渐变写在
.row上——它有负外边距，实际渲染区域比容器窄 - 确认没设
overflow: hidden且子元素溢出，导致渐变被裁切
深色模式和文字对比度是容易被跳过的硬伤
渐变一加上，text-dark 在浅渐变上可能瞬间跌破 WCAG 4.5:1 对比度标准，尤其在强光环境；深色模式下，bg-gradient-primary 仍输出亮色系渐变，和暗背景形成视觉断裂。
- 必须同步配文字色：
text-white配深渐变，text-dark配浅渐变，别信肉眼判断 - 深色模式需额外加
@media (prefers-color-scheme: dark)重写渐变值，不能复用亮色变量 - 透明度控制只能靠
rgba()色值或渐变内嵌透明 stop，opacity会连文字一起变淡
最常漏掉的其实是 fallback 色和子元素透明度——渐变本身写对了，但小屏没背景、文字看不清、卡片一盖全白，问题就出在这两处。
