必须用伪元素::before实现渐变背景上的遮罩层，因其需独立定位、z-index分层且支持响应式调节；父容器设position: relative，遮罩用rgba(0,0,0,0.3–0.5)，文字层z-index: 1并确保可访问性对比度达标。
渐变背景 + 遮罩层不是加两个 class 就完事
Bootstrap 没有 bg-gradient-overlay 这种类，直接套 bg-gradient-primary 和 bg-dark 会互相覆盖或失效——因为遮罩本质是叠加在渐变之上的半透明层，必须用定位+伪元素或额外容器实现，不能靠背景色叠加。
用 ::before 伪元素做响应式遮罩最稳妥
这是目前兼容性最好、代码最轻量的方式，尤其适配移动端 Safari 和旧版 Android WebView。
-
::before必须设content: ""、position: absolute、top: 0、left: 0、width: 100%、height: 100% - 遮罩色推荐
background: rgba(0, 0, 0, 0.4)，别用transparent或纯黑——前者在 Safari 下可能不生效，后者文字对比度崩坏 - 父容器必须带
position: relative（如class="position-relative"），否则伪元素会相对 body 定位 - 文字层需显式设
position: relative和z-index: 1，确保压在遮罩之上
断点控制遮罩强度要靠媒体查询，不是工具类
想“小屏减弱遮罩、大屏增强”，不能依赖 d-md-none 或 opacity-md-50（Bootstrap 不提供这类类）。必须写 CSS：
.hero-section {
position: relative;
}
.hero-section::before {
content: "";
position: absolute;
top: 0; left: 0; width: 100%; height: 100%;
background: rgba(0, 0, 0, 0.3);
z-index: 0;
}
@media (min-width: 768px) {
.hero-section::before {
background: rgba(0, 0, 0, 0.5);
}
}
.hero-content {
position: relative;
z-index: 1;
}
注意：断点值严格用 768px（Bootstrap 5 的 md 起点），不是 767px；background 用 rgba()，不用 hsla() 或 transparent，避免 iOS 渲染异常。
遮罩和渐变必须分层，别混在同一个 background 声明里
常见错误是试图用 background: linear-gradient(rgba(0,0,0,0.4), rgba(0,0,0,0.4)), linear-gradient(...) —— 这在 Chrome 可能工作，但在 Safari 15 及更早版本中会完全失效，且无法响应式切换。
- 渐变写在父容器的
background-image上（如background-image: linear-gradient(135deg, #0d6efd, #6f42c1)） - 遮罩用
::before单独一层，只管background和z-index - 两者互不干扰，各自可独立加媒体查询
- 如果子元素（如
.card）自带白色背景，记得改成background-color: rgba(255,255,255,0.9)，否则遮罩会被盖住
text-white，0.6 遮罩就得配 text-light 或加 text-shadow，否则 WCAG 对比度直接不及格。这不是样式问题，是可访问性硬约束。
