bootstrap 4升级到5不是换css文件就能完事，核心冲突在于结构契约、dom依赖和变量模型断裂：.form-group移除后需手动用.mb-3包裹并确保.invalid-feedback紧邻input；.row-cols-2在v5中仅md+生效，须补全断点链；.container-fluid默认加padding，需.px-0修复；.g-3同时作用于水平垂直间隙，应按需选用.gx-或.gy-；$spacers必须整体重定义为map，否则间距类缩放异常。
Bootstrap 4 升级到 Bootstrap 5 不是“换 CSS 文件”就能完事的，核心冲突来自结构契约、DOM 依赖和变量模型的断裂——直接替换 bootstrap.min.css 会导致表单验证失效、栅格错位、间距失控等静默故障。
为什么 .form-group 删除后表单就塌了
.form-group 在 v5 中被彻底移除，它从来不只是个外边距类，而是 v4 中隐含的 DOM 结构契约：label + input + .invalid-feedback 必须同级且紧邻，JS 才能正确定位反馈元素。v5 改用纯间距类（如 mb-3）手动包裹，但仅加 mb-3 会破坏这个契约。
-
.invalid-feedback必须紧跟在input后面，且与之同级；否则 Bootstrap 的 JS 不会把它关联到控件上 - 旧项目若用 jQuery 动态插入
.form-group，这段逻辑必须重写，否则验证反馈永远不显示 - 正确结构示例：
<div class="mb-3"> <label>邮箱</label> <input class="form-control"><div class="invalid-feedback">请输入有效邮箱</div> </div>
为什么 .row-cols-2 在手机上变成单列了
v4 的 .row-cols-2 全断点生效；v5 中它等价于 .row-cols-md-2，只在 md 及以上生效，xs/sm 下自动退化为单列。这不是 bug，是行为收紧。
- 所有使用处必须显式补全断点链：
.row-cols-1 .row-cols-sm-2 .row-cols-md-3 - 不能省略
.row-cols-1：否则xs下.col会按内容宽度撑开，不是预期的 100% 宽 - 嵌套
.row时，外层.g-3和内层.gy-2是叠加关系，不是覆盖——列间距可能翻倍，小屏直接挤成一列
为什么 .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，不能只改$spacer单值，否则mt-5、px-4等工具类缩放异常 - 确认所有
.col-*都直接放在.row内，不能直接塞进.container - 若只需水平间隙，用
.gx-3；只需垂直间隙，用.gy-2；两者都要才用.g-3 -
.g-0是唯一有效关闭间隙的方式，.no-gutters已废弃
为什么 .g-3 看起来“没起作用”
.g-3 没被删，但它在 v5 中默认同时作用于水平和垂直间隙；而很多旧项目实际只依赖水平间隙。一旦父容器有 overflow: hidden、position: absolute 子元素，或图片没设 max-width: 100%，就会让 .row 的 flex 拉伸失效，列宽计算异常，看起来像间隙“消失”了。
最易被忽略的是 Sass 变量体系的断裂：v5 强制用 Dart Sass，$spacers 从 list 改为 map，默认基于 1rem；只改 $spacer 而不重定义整个 $spacers map，所有间距工具类都会按错误比例缩放——这种问题在开发机上看不出，上线后才在不同设备上陆续暴露。
