必须用 JavaScript 显式调用 show()，HTML 中 class="show" 或 data-bs-show="true" 无效；DOM 就绪后才能调用，否则 document.getElementById('myModal') 返回 null 导致报错；推荐在 DOMContentLoaded 事件中初始化并调用 show()，Vue/React 中需在 mounted 或 useEffect 中配合 nextTick 或 setTimeout(0) 确保 DOM 渲染完成；避免重复初始化，应使用 bootstrap.Modal.getInstance() 检查实例是否存在；延时弹出内容为空时，应在 show.bs.modal 事件中异步加载内容并初始化子组件；服务端返回 HTML 必须为纯片段；fade 类可能导致视觉卡顿，调试时建议临时移除。
必须用 JavaScript 显式调用 show()，HTML 中加 class="show" 或 data-bs-show="true" 完全无效。
DOM 就绪后才能调用 show()
脚本若放在 <head> 里，或没等 DOM 加载完就执行 document.getElementById('myModal')，结果是 null，后续调 show() 直接报错：Cannot read properties of null (reading 'show')。
- 推荐写法：
document.addEventListener('DOMContentLoaded', () => { new bootstrap.Modal(document.getElementById('myModal')).show(); }); - 脚本放
</body>前也等效 - Vue/React 用户需在
mounted或useEffect中触发，且加nextTick/setTimeout(, 0)确保 DOM 渲染完成
避免重复初始化：同一个 Modal 元素多次 new bootstrap.Modal() 会抛错
Modal is already initialized 是常见错误。初始化前必须检查实例是否存在。
- 用全局变量缓存：
if (!window.myModalInstance) { window.myModalInstance = new bootstrap.Modal(modalEl); } - 更稳妥的方式：
bootstrap.Modal.getInstance(modalEl)?.show() || new bootstrap.Modal(modalEl).show(); - 别在每次 DOM 就绪回调里无条件新建实例
延时弹出时黑底出现但内容为空，大概率是内容没加载好
不是 JS 没跑，而是 show() 调得太早 —— 尤其当 Modal 内部依赖 fetch 加载 HTML、或含 Select2、日期控件等需手动初始化的第三方组件时。
- 别在
setTimeout后直接show()，改用show.bs.modal事件钩子，在真正渲染前注入内容 modalEl.addEventListener('show.bs.modal', async function(e) { /* fetch 后再设 innerHTML，并初始化内部组件 */ });- 服务端返回的 HTML 必须是纯片段（不含
<html>、<body>），否则innerHTML会被浏览器自动截断
最易被忽略的是 fade 动画干扰：带 fade 类的 Modal 初始 opacity 为 0，show() 后可能卡在淡入第一帧，看起来像没弹出。调试时先去掉 fade 类确认是否硬切成功，再恢复动画逻辑。
