Bootstrap 3向Bootstrap 5升级的注意事项

Bootstrap 5 移除了 data-toggle 等旧属性，改用 data-bs-toggle；工具类命名重构（如 ms/me 替代 ml/mr）；表单控件样式与字号调整；移除 jQuery 依赖，JS 组件需原生调用；结构性 HTML 变化易致静默失效。

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

Bootstrap 5 彻底移除了 data-toggle 和 data-target，改用带命名空间的 data-bs-toggle 和 data-bs-target。旧代码里只要还留着 data-toggle="collapse"，JavaScript 就完全不识别，导航栏、模态框、下拉菜单统统失效。

• 所有 <button> 或 <a> 上的触发器属性必须替换，例如：data-toggle="collapse" → data-bs-toggle="collapse"，data-target="#navbar" → data-bs-target="#navbar"
• 如果项目用了大量自定义 JS 绑定 $(...).collapse()，得全部重写为原生调用：new bootstrap.Collapse(...)
• 第三方插件（如某些旧版 bootstrap-datepicker）若未适配 v5，也会因依赖老版 data 属性而挂掉，需确认其最新版是否声明支持 Bootstrap 5

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

Bootstrap 5 重构了间距、边框、文字对齐等工具类的命名逻辑，比如 w-100 还在，但 w-25 被删了；text-center 保留，text-sm-center 却没了——断点前缀只保留在栅格和显示类上，工具类默认响应式或全屏生效。

• border-top → 仍可用，但 border-top-0 变成 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 默认将 <input>、<select>、<textarea> 的 font-size 从 1rem（16px）提到了 1.0625rem（17px），.form-label 行高、上下间距也调整过。看似微小，但在已有像素级对齐的表单布局中，常引发标签错位、输入框高度不一致、图标垂直居中偏移等问题。

• .form-control 的 padding 值变了，旧自定义 height 或 line-height 可能不再匹配，建议优先用 form-control-lg/form-control-sm 控制尺寸
• .custom-control（v4 的自定义复选框/开关）已彻底移除，必须改用 .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 把 <li> 换成了 <div> ——这种结构性变化不会报错，但功能就静默失效了。得靠真实交互路径逐页点检，不能只信视觉回归。