Bootstrap 5升级需重构结构逻辑、栅格行为和变量体系：.form-group移除后须用语义容器包裹表单元素；.row-cols-和.g-断点及间隙行为变更；$spacers等Sass变量必须整体重定义，CDN文件无法生效变量配置。
直接改类名或全局替换会出错，真正要动的是结构逻辑、栅格行为和变量体系——不是“换名字”，而是“换模型”。
为什么 .form-group 删除后表单布局就塌了
Bootstrap 5 彻底移除了 .form-group，它不再是单纯的样式类，而是 v4 中隐含的 DOM 结构契约：label + input + invalid-feedback 必须包在它里面，JS 才能正确定位验证反馈。v5 改用纯间距类（如 .mb-3）手动包裹，但如果你只把 .form-group 替换成 .mb-3，.invalid-feedback 会脱离流、定位偏移甚至不显示。
- 必须检查每处表单，把
.form-group替换为带语义的容器，比如<div class="mb-3"><label>...</label><input>...<div class="invalid-feedback">...</div></div> -
.invalid-feedback必须紧跟在input后面，且同级；否则 Bootstrap 的 JS 不会把它关联到控件上 - 如果用了 jQuery 插件动态加
.form-group，这段逻辑得重写，否则.invalid-feedback查不到父容器，验证样式永远不生效
栅格类 .row-cols-* 和 .g-* 行为变了，但你没 notice
v5 的 .row-cols-2 默认只在 md 及以上生效，不像 v4 那样全断点生效；.g-3 是水平+垂直同时设间隙，而 v4 的 .gutter 类是分开控制的。混用时，外层 .g-3 和内层 .gy-2 会叠加，不是覆盖——列间距可能翻倍，小屏直接挤成一列。
- 小屏需要双列？不能只写
.row-cols-2，得补全.row-cols-1 .row-cols-sm-2 .row-cols-md-2 -
.container-fluid在 v5 默认带padding-left/right: var(--bs-gutter-x)，左右多出空白不是 bug，是栅格间隙抽成了 CSS 变量；还原 v4 行为可加px-0或重设--bs-gutter-x: 0 - 嵌套
.row时，避免同时用.g-3和.gy-2，选一个统一层级控制，否则 DevTools 里 computedmargin会显示两个值叠加
Sass 变量和 map 结构不兼容，导致工具类缩放异常
v5 强制用 Dart Sass，$spacers 从 v4 的 list 改为 map，默认基于 1rem；如果你只改了 $spacer: 1.25rem 却没同步更新 $spacers map，mt-5、px-4 就会按旧比例缩放，间距全乱。
立即学习“前端免费学习笔记（深入）”；
- 必须重定义整个
$spacersmap，不能只改单个变量；示例：$spacers: (0: 0, 1: $spacer * .25, 2: $spacer * .5, ..., 5: $spacer * 3); -
$enable-grid-classes、$enable-responsive-font-sizes这类开关变量仍需显式设置，它们不受$prefix影响，但决定最终输出内容 - v4 的
@include bg-variant()mixin 已删除，自定义背景色得直接写 CSS：.bg-custom { background-color: map-get($theme-colors, "custom"); }
旧浮动布局和新 flex 栅格混用，页面直接塌陷
v5 的 .row 是 display: flex，但你的旧 CSS 里还有 float: left 或 inline-block，两者打架：浮动元素脱离文档流，.row 高度塌陷；.col 的 flex: 1 又不认浮动子项，列宽算不准。
- 打开 DevTools，看
.row的 computeddisplay：如果是flex，但子元素有float，说明模型冲突 - 无法重写 HTML？用
.legacy-grid包裹旧区块，并重置：.legacy-grid [class*="col-"] { float: none; width: auto; flex: 0 0 auto; } - 启用 v5.2+ 的 CSS Grid 替代方案（
$enable-cssgrid: true），用.g-col-*直接替代浮动，不依赖.row，天然隔离
最易被忽略的点：所有这些变更都依赖 Sass 编译流程。用 CDN 的 bootstrap.min.css 或预编译文件，$prefix、$enable-cssgrid、$spacers 全部无效——你调的不是变量，是死代码。
