Bootstrap 3升级到Bootstrap 5迁移注意事项

从 Bootstrap 3 直接跨到 Bootstrap 5，表面上只是版本号的跳跃，但实际上，这是一次相当彻底的底层重构。如果只是把 CSS 文件换一下，项目大概率会"原地爆炸"。这里把几个最容易踩的坑，以及背后的深层逻辑梳理清楚。

data-toggle 报错或折叠菜单不生效

Bootstrap 5 上来就给了个下马威——data-toggle 和 data-target 直接作废，换成了带命名空间的 data-bs-toggle 和 data-bs-target。你可能会发现，页面上的折叠菜单点不动，导航栏下拉菜单没反应，甚至整个页面互动都像石化了一样。原因很简单：旧代码里只要还写着 data-toggle="collapse"，JavaScript 就完全不认账了。

• 所有 或 上的触发器属性必须更新，比如：data-toggle="collapse" → data-bs-toggle="collapse"，data-target="#na vbar" → data-bs-target="#na vbar"。
• 如果项目中直接通过 $(...).collapse() 来调用，那也得重写：换成 new bootstrap.Collapse(...) 的原生方式。
• 还得留意第三方插件——比如旧版 bootstrap-datepicker，如果它们没有声明支持 Bootstrap 5，依然依赖老版 data 属性，那也会跟着挂掉。

类名批量失效：border、w、text-* 等工具类变了

这次命名逻辑的调整，影响范围相当广。比如 w-100 还在，但 w-25 直接被删了；text-center 保住了，但 text-sm-center 却消失了。断点前缀只留给了栅格和显示类，工具类默认响应式或全屏生效。这背后是设计思路的转变，但要是代码里写了一大堆旧名字，那视觉表现可就彻底乱了。

细节上更容易踩雷：

• border-top 还能用，但 border-top-0 没变名；不过 border-top-dashed 被废弃，需要拆成 border-top border-top-dashed 两条来写。
• 曾经熟悉的 ml-3/mr-3 全部失效，统一改成 ms-3/me-3（ms=margin-start，me=margin-end）。方向语义更明确了，但老代码会直接丢失外边距，页面布局可能瞬间乱成一团。
• 如果你的代码里还保留着 col-xs-6，那它早在 v4 就被删掉了，v5 中只有 col-6、col-sm-6 等。漏改的话，栅格系统会直接塌陷。

表单控件样式和字号突变

v5 把 、、 的 font-size 从 1rem（约16px）提到了 1.0625rem（约17px），.form-label 的行高和上下间距也做了调整。看起来只是几个像素的变化，但在那些像素级对齐的表单布局里，这往往会引起连锁反应：标签错位、输入框高度不一致、图标垂直居中偏移。

• .form-control 的 padding 值变了，如果你有自定义的 height 或 line-height，建议优先使用 form-control-lg/form-control-sm 来统一控制尺寸。
• v4 中那些 .custom-control（自定义复选框、开关）已经彻底退役，必须改用 .form-check + .form-switch 的新体系。否则，整个控件可能直接消失。
• 如果你是通过 Sass 自定义主题，那得注意：$input-padding-y、$form-label-margin-bottom 等变量名和默认值都不同，@include form-validation-state() 的参数签名也变了，编译时就会报错。

jQuery 依赖消失，JS 插件调用方式全换

这算是个不小的转折——Bootstrap 5 不再打包 jQuery。所有 JS 组件（Modal、Tooltip、Toast 等）必须用原生实例化，且需要依赖 bootstrap.bundle.js（包含 Popper）或单独引入 bootstrap.js + popper.js。如果你还在用 $().modal('show')，控制台会直接给你一个 TypeError: $ is not a function。

• 初始化模态框：从 $('#myModal').modal('show') 改为 new bootstrap.Modal(document.getElementById('myModal')).show()。
• 事件监听：从 $().on('shown.bs.modal', ...) 改为 document.addEventListener('shown.bs.modal', ...)。注意事件目标是 document 或具体元素，不是 jQuery 对象。
• 如果你项目里还混着其他依靠 jQuery 的库（比如 DataTables 旧版、Select2 v4），它们和 Bootstrap v5 并存倒没问题，但一旦你为了清依赖把 jQuery 删了，这些库也会崩。必须同步升级到无 jQuery 版本（比如 DataTables 2.x、Select2 4.1+）。

话说回来，实际迁移时最麻烦的往往不是改几行 class，而是那些隐式的依赖。比如某段 JS 通过 $('.btn-primary') 去找按钮再绑定 click，结果 v5 里 .btn-primary 样式没变但结构微调了；或者某处 CSS 用 .dropdown-menu > li > a 精准命中，而 v5 把