Bootstrap 5升级需全面替换data-bs-*属性、移除jQuery、更新工具类命名及表单栅格结构，否则JS组件静默失效、布局错乱。
直接升级 Bootstrap 到最新版不是改个版本号就能跑通的事——bootstrap 5.x 彻底移除了 jQuery 依赖，data-toggle 变成 data-bs-toggle，.form-group 被语义移除，ml-3 这类工具类也失效了。不处理这些，页面会静默错位、JS 组件完全不响应，控制台报 TypeError: $().modal is not a function 是最轻的后果。
先确认你用的是哪个大版本
别跳步骤。打开 package.json 或 HTML 的 <script></script> 标签，看当前引入的是 bootstrap@4.x、@3.x 还是更老的。不同起点迁移路径完全不同：
- 从 v3 升级：要重写栅格类（
.span6→.col-md-6）、替换所有.icon-*为.bi-*或 Font Awesome，且 v3 没有data-bs-命名空间 - 从 v4 升级：这是最常见的场景，重点在 jQuery 剥离、类名语义变更、
form-control尺寸和间距微调 - 从 v2 升级：已无官方支持，必须经 v3 或 v4 中转，不能直升
npm 项目：更新依赖 + 清理 jQuery
执行顺序不能错，否则 JS 组件全挂：
- 运行
npm uninstall jquery popper.js（注意不是npm rm，它不删package-lock.json） - 安装新依赖：
npm install bootstrap@latest @popperjs/core - 检查
index.html或入口 JS：删掉所有<script src="jquery.min.js"></script>和旧版popper.js引用 - 把
$(document).ready(...)全部换成document.addEventListener('DOMContentLoaded', ...) - 搜索整个项目，把
$('[data-toggle="modal"]')这类 jQuery 初始化全部重写为new bootstrap.Modal(el)
HTML 直接引用：CDN 替换 + 属性批量修正
如果没走构建流程，靠 CDN 引入，最容易翻车的地方在属性命名和 CSS 类：
- 替换
<link>和<script></script>的 CDN 地址为https://cdn.jsdelivr.net/npm/bootstrap@5.3.3（不要用latest，避免意外升级） - 全局搜索替换：
data-toggle→data-bs-toggle，data-target→data-bs-target，data-dismiss→data-bs-dismiss -
ml-3/mr-3必须改为ms-3/me-3；text-sm-center失效，统一用text-center（v5 工具类默认响应式） -
.btn-outline-light不是“不能用”，而是颜色值变了——它现在是浅灰，如需白色边框按钮，得写.btn-outline-white
表单和栅格：结构变化常被忽略
这两个地方没有报错，但布局会悄悄崩坏：
-
.form-group不再是必需容器，但也不能直接删——要手动加mb-3等间距类，否则 label 和 input 会贴在一起 -
.row-cols-2在 v5 中只在md及以上生效，小屏自动退化为单列。原来靠它实现的 xs 双列，必须显式写成.row-cols-2 .row-cols-sm-2 -
.card-deck已废弃，换成.card-group后，要用gap控制卡片间距，否则会塌陷 -
.custom-control（v4 的开关/复选框）彻底删除，必须改用.form-check .form-switch结构，否则控件不可见
最麻烦的往往不是改代码，而是那些没写进文档的隐性依赖：比如某个自定义 tooltip 插件内部硬编码了 data-toggle，或者某段 Sass 混合宏里还引用着 $enable-rounded: true 以外的旧变量。上线前务必在真实设备上逐页点开模态框、下拉菜单、表单验证反馈——静默失效比报错更难排查。
