bootstrap 4 升级到 5 是涉及 js、css、构建三端断裂的实质性迁移，需清除 jquery 依赖、避免 form-group 盲替、补全 row-cols 断点、适配 dart sass 变量，并真机验证关键路径。
Bootstrap 4 升级到 5 不是“改几个类名就能跑”的小修小补，而是涉及 JS 运行时、CSS 语义、构建链路三端断裂的实质性迁移——但只要避开 jQuery 残留和 form-group 盲替这两个最大雷区，其余问题基本可控。
jQuery 依赖残留导致所有 JS 组件静默失效
这是最常被低估、后果最严重的问题：哪怕你项目里只引入了 jquery 但完全没调用它，只要 bootstrap.js 加载前 $ 已存在，Bootstrap 5 就会误判为“兼容模式”，进而跳过原生组件初始化逻辑。结果就是 modal 打不开、dropdown 点不动、toast 不弹出，控制台却无报错。
- 执行
npm uninstall jquery popper.js（不是npm rm，后者不删package-lock.json） - 安装新版 Popper：
npm install @popperjs/core - 全局搜索
$(，把所有$(selector).modal('show')类写法替换为new bootstrap.Modal(el).show() - 检查
document.addEventListener('DOMContentLoaded', ...)是否替代了全部$(document).ready(...)
form-group 不能全局替换为 mb-3
form-group 在 Bootstrap 5 中被彻底移除，但它承担的不只是间距功能——还隐含了 label+control 的语义包裹、验证反馈定位、响应式断点对齐等逻辑。直接批量替换成 mb-3 会导致表单在小屏错位、:valid/:invalid 样式不触发、form-text 偏移。
- 保留结构语义：每个表单控件应包裹在
<div class="mb-3"> 内，里面放 <code><label></label>和<input class="form-control"> - 验证反馈需显式加
invalid-feedback或valid-feedback类，且必须紧跟在form-control后 - 若用 JS 动态设置校验状态，必须调用
el.reportValidity()触发伪类，仅设setCustomValidity('')不够 - 所有
.row-cols-*使用处必须显式补全断点：.row-cols-1 .row-cols-sm-2 .row-cols-md-3 - 注意
.col-auto行为微调：配合.w-100换行时，v5 中可能多出意外空隙，需加flex-shrink-0或测试实际渲染 -
.row默认display: flex，但若子列含position: absolute或图片未设max-width: 100%，会破坏等高拉伸，需手动加align-items: stretch - 运行
npm install sass --save-dev替换 LibSass - 不要直接
@import "bootstrap/scss/bootstrap"，先按官方迁移指南检查变量映射表 - 重点核对：
$spacer（默认1rem）、$enable-shadows（v5 默认false）、$border-radius（单位从px改为rem） - 若用 Webpack，确认
sass-loader版本 ≥ 12，否则无法解析新语法
.row-cols-* 断点行为变严格，移动端容易漏列数
v4 中 .row-cols-2 默认在所有尺寸生效；v5 中它只在 xs 断点起效，且不再向下兼容。这意味着你原来写的 .row-cols-2 在 v5 的 sm 及以上断点会退化成单列——而你可能在测试时只看了桌面端，根本没注意到手机上变窄了。
Dart Sass 和变量系统不兼容，自定义主题易编译失败
v5 强制使用 Dart Sass，且重命名了大量 Sass 变量（如 $spacers 结构变更、$enable-rounded 默认值翻转）。如果你项目里有自定义 _custom.scss 并覆盖了旧变量，大概率会编译报错或样式错乱。
真正麻烦的从来不是“要改多少行”，而是那些不会报错、只在特定设备或交互路径下才暴露的问题：比如 data-toggle 忘加 bs- 前缀导致 modal 静默失败，或者 .card-body 替换遗漏让 header 背景色消失。建议升级后优先在真机上跑通表单提交、模态框嵌套、文件上传三个高频路径，比扫代码更早发现问题。
