modal()必须在dom就绪后调用，否则不显示；正确做法是用$(function(){})或domcontentloaded；bootstrap 4依赖jquery，5为es模块；vue/react需$nexttick；data-bs-toggle失效主因是target缺失#、modal被手动隐藏或ajax加载未重初始化；backdrop失效多因z-index冲突；事件须绑定在modal元素上且注意大小写。
modal() 方法必须等 DOM 就绪后调用
直接在 <script></script> 标签里写 $('#myModal').modal() 但没等页面加载完，模态框大概率不显示，控制台也不报错——这是最常被忽略的触发时机问题。
正确做法是包在 jQuery 的就绪回调里，或者用原生 DOMContentLoaded：
$(function() {
$('#myModal').modal('show');
});
- 如果用原生 JS + Bootstrap 5，得确保
bootstrap.bundle.min.js已加载，且调用new bootstrap.Modal(...)前 DOM 节点存在 - Bootstrap 4 和 5 的 JS 初始化方式不同：4 依赖 jQuery，5 是纯 ES 模块，混用会报
TypeError: $(...).modal is not a function - Vue/React 项目中动态挂载模态框时，别在组件
mounted阶段立刻调.modal('show')，要加$nextTick或setTimeout确保元素已渲染
data-bs-toggle="modal" 不生效的三个常见原因
点击按钮没反应，不是 HTML 写错了，而是背后链路断了。Bootstrap 的触发机制依赖三要素同时成立：属性存在、href 或 data-bs-target 指向正确 ID、对应 <div class="modal"> 在 DOM 中且未被移除。<ul>
<li>
<code>data-bs-target 值必须带 #，比如 data-bs-target="#loginModal"，漏掉就静默失败
display: none 或 visibility: hidden 预先隐藏——Bootstrap 自己用 display: none 控制显隐，手动加会导致样式冲突data-bs-toggle 绑定只在初始 DOM 上生效，后续插入的内容需手动初始化：new bootstrap.Modal(document.getElementById('ajaxModal'))
modal-backdrop 和 z-index 容易引发遮罩层失效
点背景关闭不了模态框，或弹出后页面其他元素还能点，基本是 backdrop 层没起来，根源常出在 z-index 或 CSS 干扰上。
- Bootstrap 默认 backdrop 层
z-index是 1050，modal 本体是 1055；如果你全局设了* { z-index: 9999 }，backdrop 就会被压在下面 -
data-bs-backdrop="false"会让遮罩消失，但不会自动禁用点击关闭——这时得手动监听click并调hide() - 某些 UI 库（如 Element Plus）也用固定
z-index，和 Bootstrap 冲突时，优先覆盖.modal-backdrop的z-index，别动整个 modal 的层级
modal 的 show/hide 事件监听必须在 modal 元素上绑定
很多人把事件监听写在按钮上，比如 $('#openBtn').on('shown.bs.modal', ...)，结果永远不触发——因为 shown.bs.modal 是发给 modal 本体的，不是触发按钮。
- 正确写法：
$('#myModal').on('shown.bs.modal', function () { console.log('已显示'); }) - 事件名大小写敏感：
shown.bs.modal不是show.bs.modal（后者不存在） - 如果 modal 是动态创建的，事件监听得用委托：
$(document).on('hidden.bs.modal', '#dynamicModal', handler) - Bootstrap 5 移除了 jQuery 事件，改用
modalEl.addEventListener('shown.bs.modal', handler)，别混用旧写法
modal 的生命周期钩子看似简单，但事件源、触发时机、初始化顺序这三点一错，调试时连日志都打不出来。尤其在 SSR 或微前端环境里，DOM 存在性比想象中更脆弱。
