bootstrap 5 升级不是平滑过程，而是结构性重构：类名变更伴随dom契约、栅格断点、css变量等深层调整，需逐项修复语义容器、断点声明、间距逻辑及颜色语义。
没有“平滑升级”这回事。Bootstrap 5 的 CSS 变更不是样式微调，而是结构契约、栅格语义和变量体系的重构——直接全局替换类名，表单验证错位、卡片列宽塌陷、小屏栅格消失都是必然结果。
.form-group 被删了，但你不能只加 .mb-3
它从来不只是个间距类：v4 中 .form-group 是 label + control + .invalid-feedback 的 DOM 容器契约，JS 靠它定位反馈元素。v5 移除后，仅用 .mb-3 会导致：
-
.invalid-feedback脱离文档流，悬在控件上方或下方偏移位置 - 小屏下
: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 后，且同级；若用 jQuery 动态插入，那段逻辑必须重写，否则 JS 找不到父容器，验证永远不生效。
.row-cols-* 和 .g-* 在小屏上突然失效
v4 的 .row-cols-2 全断点生效；v5 中它等价于 .row-cols-md-2，xs/sm 下自动退化为单列。这不是 bug，是断点规则收紧。
如果你了解HTML，CSS和JavaScript，您已经拥有所需的工具开发Android应用程序。本动手本书展示了如何使用这些开源web标准设计和建造，可适应任何Android设备的应用程序 - 无需使用Java。您将学习如何创建一个在您选择的平台的Android友好的网络应用程序，然后转换与自由PhoneGap框架到一个原生的Android应用程序。了解为什么设备无关的移动应用是未来的潮流，并开始构建应用程序，提供更
- 小屏需要双列？必须显式补全：
.row-cols-1 .row-cols-sm-2 .row-cols-md-2 - 漏掉
.row-cols-1：xs 下.col会按内容宽度撑开，不是预期的 100% 宽 - 嵌套
.row时，外层.g-3和内层.gy-2是叠加关系，不是覆盖——可能产生 3rem + 2rem = 5rem 的意外空白
别混用 .g-* 和 .gy-*/.gx-*，选一个层级统一控制间隙，否则 DevTools 里 computed margin 会显示两个值叠加。
.container-fluid 左右突然多出空白
v5 给 .container-fluid 默认加了 padding-left/right: var(--bs-gutter-x)，这是栅格间隙抽成 CSS 变量的结果。v4 的 .container-fluid 是纯 width: 100%，无 padding。
- 最快修复：
<div class="container-fluid px-0"> <li>全局还原：在 <code>:root里重设--bs-gutter-x: 0，但会影响所有.gx-*类行为 - 若你自定义了 Sass 变量
$spacers，必须同步更新整个 map（不能只改$spacer），否则mt-5、px-4会按旧比例缩放，间距全乱 - 检查是否误用了
.btn-outline-light但期望白边效果 - 若项目中自定义了
$theme-colors，确认white键是否已正确定义为#fff - 不要依赖“看起来像”，用 DevTools 查看 computed
color值验证
.btn-outline-light 看起来变灰了
这不是 bug，是语义重定义：light 在 v5 中指代灰阶色 #f8f9fa（即 $gray-100），不再是纯白。你想要白色边框，必须显式写 .btn-outline-white。
真正难的不是改类名，而是识别哪些地方依赖了被删类的隐含行为——比如 .card-deck 废弃后，flex 间距逻辑失效；.text-hide 删除后，.visually-hidden 若父容器有 overflow: hidden，文字仍可能意外显示。这些静默故障，只有逐页 inspect + 测试才能暴露。
