bootstrap 5 升级无平滑迁移：.form-group 等类被移除，需手动结构包裹；.btn-outline-light 语义变更；.row-cols-* 需补全断点；.container-fluid 默认加内边距；.text-hide 替换为 .visually-hidden 需真机验证。
没有“平滑迁移”这回事，.form-group、.card-deck、.text-hide 这些类名不是改个名字就能用的，盲目替换会直接导致表单反馈错位、卡片列宽塌陷、隐藏文字意外显示等静默故障。
为什么 .form-group 不能替换成 .mb-3
.form-group 在 Bootstrap 5 中被彻底移除，它承担的不只是外边距功能——而是 label 与控件的语义包裹、.invalid-feedback 的 DOM 邻接定位、响应式断点对齐逻辑。仅加 .mb-3 会导致：
- 验证反馈元素脱离文档流，悬在控件上方或下方偏移位置
- 小屏下
:valid/:invalid伪类不触发，前端校验视觉失效 -
.form-text偏离控件底部，与.form-control失去垂直对齐
正确做法是手动包裹：<div class="mb-3">
<label>邮箱</label><input class="form-control"><div class="invalid-feedback">请输入有效邮箱</div>
</div>，且 .invalid-feedback 必须紧跟 .form-control 后。
.btn-outline-light 改成 .btn-outline-white 后按钮变灰了
这不是 bug，是语义重定义：light 在 v5 中指代灰阶色 #f8f9fa（即 $gray-100），不再是纯白。你想要白色边框，必须显式写 .btn-outline-white。
- 检查是否误用了
.btn-outline-light但期望白边效果 - 若项目中自定义了
$theme-colors，确认white键是否已正确定义为#fff - 不要依赖“看起来像”，用 DevTools 查看 computed color 值验证
.row-cols-2 在手机上变成单列了
v4 的 .row-cols-2 全断点生效；v5 中它等价于 .row-cols-md-2，只在 md 及以上生效，xs/sm 下自动退化为单列。
- 所有使用处必须显式补全断点链：
.row-cols-1 .row-cols-sm-2 .row-cols-md-3 - 别漏掉
.row-cols-1：否则 xs 下.col会按内容宽度撑开，不是预期的 100% 宽 - 嵌套
.row时，外层.g-3和内层.gy-2是叠加关系，不是覆盖——可能产生 3rem + 2rem = 5rem 的意外空白
.container-fluid 左右突然多出空白
v5 给 .container-fluid 默认加了 padding-left/right: var(--bs-gutter-x)，这是栅格间隙抽成 CSS 变量的结果。v4 的 .container-fluid 是纯 width: 100%，无 padding。
- 最快修复：加
px-0，即<div class="container-fluid px-0"> <li>全局还原：在 <code>:root里重设--bs-gutter-x: 0，但会影响所有.gx-*类行为 - 注意：若你自定义了 Sass 变量
$spacers，必须同步更新整个 map，否则.g-3计算值会错乱
最易被忽略的是 .text-hide → .visually-hidden 的替换：后者依赖 clip + overflow: hidden 实现，若父容器本身有 overflow: hidden，文字仍可能意外显示——必须真机测试关键路径。
