Bootstrap 5 迁移是重写式替换而非升级：必须清除 jQuery 和 popper.js，改用 @popperjs/core；所有 JS 调用改为原生 API；.form-group 彻底移除，需手动重构表单结构；.row-cols-* 默认仅中屏生效，须显式补全断点；类名变更反映语义重定义，无向后兼容。
Bootstrap 4 到 5 的迁移不是“升级”，而是重写式替换：jQuery 必须清空，data-toggle 全部失效，.form-group 不是改个类名就能用，.row-cols-2 在手机上直接退化为单列——这些都不是配置问题，是底层语义和渲染逻辑的断裂。
必须先清除 jQuery 和旧 Popper
哪怕项目里没写一行 $()，只要 jquery 或 popper.js 还在 node_modules 或 package.json 里，所有 Bootstrap 5 原生 JS 组件（modal、dropdown、tooltip）都会静默失败，控制台报 TypeError: $().modal is not a function 或完全无响应。
- 执行
npm uninstall jquery popper.js（别用npm rm，它不删package-lock.json） - 装新依赖：
npm install @popperjs/core（注意是@popperjs/core，不是popper.js） - 所有
$(document).ready()替换为document.addEventListener('DOMContentLoaded', ...) - 所有
$('...').modal('show')类调用，改用new bootstrap.Modal(el)或bootstrap.Modal.getInstance(el)
表单结构不能靠查找替换修复
.form-group 在 Bootstrap 5 中被彻底移除，它承担的不只是外边距——而是 label 与控件的包裹关系、.invalid-feedback 的 DOM 邻接定位、以及响应式断点对齐逻辑。全局替换成 .mb-3 会导致验证反馈悬空、伪类校验失效、.form-text 错位。
- 每处表单控件都得手动包裹：
<div class="mb-3"> <label>邮箱</label><input class="form-control"><div class="invalid-feedback">请输入有效邮箱</div> </div> -
.invalid-feedback必须紧跟.form-control后，不能隔元素、不能用 flex 排列 -
select和type="range"已从FormControl移除，React-Bootstrap 用户需改用FormSelect和FormRange
栅格与间距类行为收紧，小屏表现最容易翻车
v4 的 .row-cols-2 全断点生效；v5 中它等价于 .row-cols-md-2，xs/sm 下自动退化为单列——页面看着没问题，但真机测试时用户一划就发现列表变单列了，而你根本没注意到。
- 所有
.row-cols-*使用处必须显式补全断点链：.row-cols-1 .row-cols-sm-2 .row-cols-md-3 -
.container-fluid默认加了padding-left/right: var(--bs-gutter-x)，左右突然多出空白？不是 bug，是 v5 把栅格间隙抽成 CSS 变量了；最快修复是加px-0 -
.g-3是垂直+水平同时生效，.gy-2仅控制行间距；嵌套.row时，外层.g-3和内层.gy-2是叠加关系，可能产生 5rem 空白
类名变更背后是语义重定义，不是颜色或间距微调
.btn-outline-light 改成 .btn-outline-white 后按钮变灰？这不是 bug，是 light 在 v5 中已重新定义为灰阶色 #f8f9fa（即 $gray-100），不再是纯白。你想要白色边框，就必须显式写 .btn-outline-white。
-
.card-deck废弃，改用.card-group+.gap-3，但旧样式依赖.card-deck的 flex 间距逻辑，嵌套时列宽会不均 -
.text-hide彻底删除，必须用.visually-hidden，且该类依赖clip+overflow实现，若父容器有overflow: hidden，文字仍可能意外显示 - 自定义 Sass 变量如
$spacers必须同步更新整个 map，默认基于1rem；只改$spacer: 1.25rem会导致mt-5、px-4缩放异常
最常被忽略的是：所有变更都不可逆向兼容，没有“渐进式”开关。一个 .form-group 漏改，整页表单验证视觉就失效；一处 .row-cols-2 没补断点，小屏用户看到的就是单列列表——这些故障不会报错，只会静默错位。
