宽屏才启用背景渐变的正确做法是用@media (min-width: 992px)精确控制background-image，而非依赖bg-gradient-primary d-lg-block组合；后者中渐变始终生效，仅display变化，且需配合bg-primary等颜色类、避免$enable-gradients: false禁用、适配深色模式与文字对比度。
宽屏模式（通常指 lg 或 xl 断点）下启用背景渐变，不能靠 bg-gradient-primary d-lg-block 这类组合实现——它只是让元素在宽屏显示，但渐变本身从小屏就已生效，不是“宽屏才启用”。真正可控的做法是用媒体查询精准控制 background-image 的注入时机。
为什么 bg-gradient-primary d-lg-block 不等于“宽屏才渐变”
因为 bg-gradient-primary 是一个无条件生效的工具类，它在所有断点都写死了一条 background-image: linear-gradient(135deg, ...) 规则；d-lg-block 只控制 display，不删也不禁用渐变样式。小屏时元素可见、渐变照常渲染，你只是没意识到而已。
- 常见错觉：小屏看不到渐变 → 实际是被子元素（如
.card）的纯白背景完全盖住了 -
bg-gradient-primary必须搭配bg-primary等颜色类才触发，单独使用无效 - 若项目 SCSS 中设了
$enable-gradients: false，所有渐变类静默失效，控制台无提示
用 @media (min-width: 992px) 精确控制宽屏渐变
Bootstrap 5 的 lg 断点值是 992px，必须严格匹配，写成 991px 或 993px 都会失效。基础态（小屏）先设纯色，再在媒体查询中覆盖 background-image：
.hero {
background-color: #f8f9fa;
}
@media (min-width: 992px) {
.hero {
background-image: linear-gradient(135deg, #0d6efd, #6f42c1);
}
}
- 务必用
background-image，不是background—— 后者会清掉background-color，导致小屏回退失败 - 方向优先写角度（如
135deg），比to right兼容性更稳，尤其对旧版 Safari - 颜色至少两个，否则浏览器仍渲染为纯色，不是渐变
宽屏渐变 + 深色模式适配要额外加一层 @media (prefers-color-scheme: dark)
如果用户开启系统深色模式，而你的宽屏渐变仍是亮色系（比如 #0d6efd → #6f42c1），文字可能直接看不清。不能指望断点类自动切换，必须手动重写：
@media (min-width: 992px) and (prefers-color-scheme: dark) {
.hero {
background-image: linear-gradient(135deg, #3b5bdb, #8a63d2);
}
}
- 别复用
$primary变量直接生成深色渐变——它的默认值是亮色，得另配一套暗色变量 - 渐变生效后，文字对比度大概率跌破 WCAG 标准，必须同步调文字色：
text-white配深渐变，text-dark配浅渐变 - 子元素如
.card默认白色背景会盖住容器渐变，需改为background-color: rgba(255, 255, 255, 0.9)留透出空间
按钮等组件上加宽屏渐变要绕过 !important 锁定
直接给 .btn 加 bg-gradient-primary 无效，因为 Bootstrap 按钮用 !important 固定了 background-color，且未预留 background-image 注入点。正确做法是显式覆盖：
.btn-wide-gradient {
background-color: transparent !important;
background-image: linear-gradient(135deg, #0d6efd, #6f42c1) !important;
}
@media (max-width: 991.98px) {
.btn-wide-gradient {
background-image: none !important;
}
}
- 必须加
!important，否则按钮原生样式权重更高 - 小屏用
@media (max-width: 991.98px)清空渐变，而不是依赖d-lg-block控制显隐 - 记得补
.btn-wide-gradient:hover和:active，否则悬停时背景变透明
最易被忽略的其实是子元素背景和文字对比度——渐变一加上，.card、.alert 这些自带纯色背景的组件立刻变成“遮罩层”，而肉眼判断的文字可读性在阳光直射屏幕时基本不可信。得实测，不能只看开发机。
