<p>Bootstrap 5 升级需彻底清除 jQuery 和 popper.js 依赖，改用 @popperjs/core；重写 JS 初始化逻辑，替换 data-toggle 为 data-bs-toggle，更新类名如 .btn-outline-light→.btn-outline-white、.row-cols-* 补全断点，调整表单结构与栅格行为，并确保 CSS/JS 版本及构建工具（Dart Sass）同步更新。</p>
jQuery 依赖必须彻底清除，否则 JS 组件全失效
bootstrap 5 彻底移除了对 jquery 和旧版 popper.js 的依赖，如果你的项目里还留着它们，哪怕只是没用到，也会导致 bootstrap.modal、bootstrap.dropdown 等原生 js 组件初始化失败——控制台报错 typeerror: $(...).modal is not a function 或静默无响应。
- 执行
npm uninstall jquery popper.js（不是npm rm，后者不删package-lock.json） - 安装新版 Popper：
npm install @popperjs/core（注意是@popperjs/core，不是popper.js） - 检查所有 JS 初始化代码：把
$(document).ready(...)全部换成document.addEventListener('DOMContentLoaded', ...) - 搜索项目中所有
$()调用——尤其是模态框、提示框、折叠菜单的触发逻辑，全部重写为bootstrap.XXX.getInstance(el)或new bootstrap.XXX(el)
类名变更不是“查找替换”能搞定的，form-group 是典型雷区
.form-group 在 Bootstrap 5 中被完全移除，但它不是简单替换成另一个类——而是语义和结构逻辑变了。直接全局替换为 .mb-3 会导致表单间距失控、响应式断点错乱、验证反馈错位。
- 表单控件外层不再强制需要包裹容器，但需手动加间距类：
<div class="mb-3"><label>...</label><input class="form-control"></div> -
.btn-outline-light→ 必须改为.btn-outline-white（不是.btn-outline-light失效，而是颜色值变了，light在 v5 中指代灰色系） -
.card-deck已废弃，改用.card-group+ 手动gap控制间距（CSS Grid / Flex 逻辑不同，旧样式会塌陷） - 所有
.text-*类（如.text-muted）保留，但.text-hide彻底删除，需用visually-hidden
栅格系统升级后，.row-cols-* 行为更严格，移动端容易漏断点
Bootstrap 5 的 .row-cols-* 类现在只在对应断点及以上生效，且不再自动向下兼容。比如 .row-cols-sm-2 在 xs 下会退化成单列，但如果你原来靠 .row-cols-2（v4 写法）实现小屏双列，升级后 xs 下就变成单列了——而你可能根本没注意到。
- 检查所有
.row-cols-*使用处，显式补全断点：.row-cols-1 .row-cols-sm-2 .row-cols-md-3 -
.col-auto的最小宽度行为有微调，配合.w-100换行时需测试是否多出空隙 - SCSS 变量中
$grid-breakpoints默认值已变（xs: 0,sm: 576px…），若项目自定义过断点，需同步更新src/scss/_variables.scss - 构建工具若仍用 Libsass（如旧版 gulp-sass），编译会失败；必须切换到 Dart Sass：
npm install sass --save-dev
CDN 和构建链路要同步更新，否则 CSS 和 JS 版本不对齐
只换 bootstrap.min.css CDN 链接，却不换 JS 文件，或只更新 npm 包却不重建 CSS，都会导致组件样式错乱——比如 offcanvas 有动画但没背景遮罩，或 form-check-input 复选框不显示对勾。
- CDN 必须配对更新：
https://cdn.bootcdn.net/ajax/libs/twitter-bootstrap/5.3.0/css/bootstrap.min.css+https://cdn.bootcdn.net/ajax/libs/twitter-bootstrap/5.3.0/js/bootstrap.bundle.min.js - 若用 Sass 编译，确认
@import "bootstrap/scss/functions";等路径指向的是 node_modules 中的 v5 版本，而不是本地缓存的老文件 - 检查
index.html或模板中是否硬编码了data-toggle属性——全部改为data-bs-toggle（所有 data 属性都加了bs-前缀） - 第三方插件如
bootstrap-fileinput也得升到 5.x，它内部仍调用$.fn.modal，不升级会直接报错
最常被跳过的其实是浏览器兼容性兜底——Bootstrap 5 不再支持 IE11，如果你的客户还在用旧内网系统，得单独判断 UA 加载降级样式，而不是指望“看起来差不多”。
