card-img-overlay必须是.card的直接子元素，否则因定位上下文断裂导致文字偏移；需配合.card的position: relative和card-img（非card-img-top）使用，并设width: 100%与object-fit: cover以确保铺满。
card-img-overlay 必须是 .card 的直接子元素
否则定位会失效，文字浮到页面顶部或完全偏移。Bootstrap 的 card-img-overlay 依赖父级 .card 的 position: relative 做绝对定位，如果中间插了 div 或其他容器，这个上下文就断了。
常见错误写法：
div，card-img-overlay 就找不到正确的定位根节点。
正确结构只允许一层嵌套：
<div class="card">
@@##@@
<div class="card-img-overlay">
<h5 class="card-title">标题</h5>
<p class="card-text">正文</p>
</div>
</div>
card-img 不等于 card-img-top，用错就铺不满
card-img-top 是块级元素、占文档流，适合当“插图”放在文字上方；而 card-img 才是真正做背景图的类——它不占流、默认 position: absolute，配合 width: 100% 和 object-fit: cover 才能撑满卡片底图。
容易踩的坑：
- 没给
card-img加width: 100%→ 图片只显示原始尺寸 - 没设
object-fit: cover→ 图片被拉伸变形或留白 - 父容器
.card没高度（比如里面只有card-img-overlay）→ 图片区域塌陷，文字悬空
推荐补一句 CSS 防御：.card { min-height: 200px; } 或根据业务设固定高。
图片加载失败时文字看不见怎么办
card-img-overlay 默认是纯白文字，在图片没加载出来、或加载失败变成空白背景时，文字直接隐身。这不是 bug，是设计预期——但实际项目必须处理降级。
解决方式有三个，按优先级推荐：
- 给
.card设一个柔和的 fallback 背景色，比如bg-light或bg-secondary，保证文字始终可读 - 在
card-img上加onerror="this.style.display='none'"，再配合card-img-overlay的 padding 做视觉平衡 - 用
aria-hidden="true"+ 单独放一段sr-only文字，兼顾无障碍访问
别依赖「用户总会看到图」，网络抖动、CDN 故障、404 都会让图片消失几秒甚至全程不出现。
hover 遮罩动画闪一下？大概率是 overflow 或 transition 写错了
想在图片上加 hover 遮罩（比如半透明色块+文字浮现），很多人直接套 card-img-overlay 加 :hover，结果一动就闪、或动画卡顿。
根本原因有两个：
-
.card被父级设了overflow: hidden，但遮罩层因定位问题溢出裁剪区 → 加overflow: hidden到.card自身（Bootstrap 5 默认没设，得手动补） -
transition: all 0.3s导致浏览器疯狂重绘 → 改成明确属性：transition: opacity 0.3s, transform 0.3s
另外，card-img-overlay 默认有 padding: 1.25rem，hover 动画若涉及位移（如 transform: translateY(-10px)），记得在 :hover 状态里同步调整 padding 或用 top 控制，否则文字跳动明显。
