类名变更必须人工核对上下文，如.form-group移除、.btn-outline-light→.btn-outline-white、.card-deck废弃、.text-hide删除、栅格间距类行为差异、容器默认内边距变化及Sass变量同步更新等，均不可全局替换。
直接结论：类名不是“全局查找替换”就能搞定的，很多变更背后是语义逻辑和渲染行为的重构，盲目替换会导致表单错位、栅格塌陷、间距失控等静默问题。
哪些类名变更必须手动逐处检查
不是所有类名都只是“换名字”。以下几类必须人工核对上下文，不能靠 IDE 全局替换：
-
.form-group被彻底移除 —— 它不是替换成.mb-3就完事，而是结构逻辑变了：原来强制包裹<label>和控件，现在推荐用<div class="mb-3">手动包裹，否则验证反馈（.invalid-feedback）可能脱离 DOM 流、定位错乱 -
.btn-outline-light→.btn-outline-white—— 名字改了，但本质是颜色值重定义：light在 v5 中已指代灰阶色（#f8f9fa），不再是白色；若你期望的是纯白边框，必须写.btn-outline-white -
.card-deck已废弃 —— 替代方案是.card-group+.gap-3（或.gy-3），但旧样式里依赖.card-deck的 flex 间距逻辑会失效，尤其在嵌套容器中容易出现列宽不均 -
.text-hide彻底删除 —— 必须改为.visually-hidden，且该类依赖clip+overflow组合实现，若父容器有overflow: hidden，文字仍可能意外显示
栅格与间距类的行为差异最容易被忽略
v5 的 .row-cols-* 和 .g-* 看似只是加了个前缀，实则底层规则收紧：
-
.row-cols-2在 v4 中默认全断点生效，v5 中只在md及以上生效（即.row-cols-md-2），xs/sm 下退化为单列 —— 若你页面有小屏双列需求，必须显式补全.row-cols-1 .row-cols-sm-2 .row-cols-md-2 -
.g-3是垂直+水平同时生效，而.gy-3仅控制行间距、.gx-2仅控制列间距；嵌套.row时，外层.g-3和内层.gy-2是叠加关系，不是覆盖，可能导致间距翻倍 -
.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，mt-5、px-4等工具类会缩放异常 - 旧版 Sass 中常用
@include bg-variant(...)，v5 中该 mixin 已移除，必须改写为直接声明 CSS 规则：.bg-custom { background-color: $value !important; } - 所有组件级变量（如
$alert-bg、$dropdown-link-color）现在都通过 CSS 变量暴露（--bs-alert-bg等），若你用 JS 动态读取样式，得改用getComputedStyle获取--bs-xxx值，而非直接访问 Sass 变量
最麻烦的不是“哪里变了”，而是“变在哪里用了”——尤其是那些散落在 JS 模板字符串、CMS 输出 HTML、第三方插件生成的 DOM 中的类名。建议先用浏览器 DevTools 的 “Computed” 面板定位异常渲染区域，再逆向追踪对应类名的上下文，比通读迁移指南更高效。
