bootstrap 5 升级无捷径，.form-group 等类名不能简单映射，需逐项对照官方指南并实测 dom 与渲染效果，因类名变更常伴随布局逻辑、css 流行为及响应式规则重构。
直接结论：没有“快速迁移”的捷径，.form-group、.card-deck、.text-hide 这类关键类名不能靠映射表一换了事，盲目替换会引发布局塌陷、验证反馈错位、小屏列数归零等静默故障。
哪些类名看似能映射，实则必须逐处重审
官方迁移指南里列出的“类名对应关系”只是起点，不是操作指令。以下几类必须打开浏览器开发者工具，逐个检查 DOM 结构和渲染效果：
-
.form-group被彻底移除 —— 不是加个.mb-3就完事。旧结构中它包裹<label></label>和控件，确保.invalid-feedback正确跟随；v5 中若只加间距类，反馈元素可能脱离流、悬空或错位 -
.btn-outline-light→.btn-outline-white—— 名字改了，但语义变了：light在 v5 中指代灰阶色#f8f9fa，不是白色；你想要纯白边框，必须写.btn-outline-white，否则按钮边框会变浅灰 -
.card-deck已废弃 —— 替换成.card-group+.gap-3后，flex 项的flex: 1 1 0行为被取消，卡片宽度不再均分；嵌套时尤其容易出现列宽不一致 -
.text-hide彻底删除 —— 必须用.visually-hidden，但它依赖clip+overflow: hidden实现；若父容器本身有overflow: hidden，文字仍可能意外显示
栅格与间距类的行为差异最容易漏掉
v5 的 .row-cols-* 和 .g-* 看似只是加前缀，实则规则收紧，小屏表现常与预期不符：
-
.row-cols-2在 v4 中全断点生效，v5 中默认只在md及以上生效（即等价于.row-cols-md-2）；若你页面在 xs 下需双列，必须显式补全.row-cols-1 .row-cols-sm-2 .row-cols-md-2 -
.g-3是垂直+水平同时生效，而.gy-3仅控制行间距、.gx-2仅控制列间距；外层.row.g-3套内层.row.gy-2，间距会叠加而非覆盖，可能导致 3rem + 2rem = 5rem 的意外空白 -
.container-fluid在 v5 中默认带padding-left/right: var(--bs-gutter-x)—— 页面左右突然多出空白？不是 bug，是 v5 把栅格间隙抽成 CSS 变量了；还原 v4 行为需加px-0或在::root重设--bs-gutter-x: 0
自定义 CSS 和 Sass 变量必须同步更新
如果你项目中有覆盖 Bootstrap 的 Sass 变量（比如 $spacers、$theme-colors），升级后大概率失效：
- v5 强制使用 Dart Sass，且
$spacers是一个 map，默认基于1rem；若你只改了$spacer: 1.25rem却没同步更新$spacersmap，所有.p-*、.m-*类的值都会错乱 -
$grid-breakpoints默认值已变（xs: 0,sm: 576px…），若你自定义过断点，必须同步更新src/scss/_variables.scss中的完整 map - 旧版
@include bg-variant(".bg-#{$color}", $value)写法已不兼容，需改为显式声明：.bg-#{$color} { background-color: $value !important; }
最常被忽略的复杂点是：类名变更背后往往是渲染逻辑重构，而不是简单重命名。比如 .form-group 移除后，表单验证反馈的 DOM 位置、CSS 流式行为、响应式断点继承都变了——这些无法靠查找替换发现，只能靠真实设备/模拟器逐页测试。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
