react组件卸载后需手动调用bootstrap插件实例的dispose()方法清理dom事件和data属性，否则会导致内存泄漏、重复初始化及“cannot read property 'queryselector' of null”等错误。
React组件卸载后Bootstrap JS仍操作DOM
Bootstrap的JS插件（比如 Modal、Dropdown）依赖直接操作DOM节点并绑定事件监听器，而React控制虚拟DOM和真实DOM的生命周期。当React组件卸载时，它不会自动清理Bootstrap手动挂载的事件或定时器，导致内存泄漏、重复初始化、甚至 Cannot read property 'querySelector' of null 这类错误。
常见现象：点击按钮打开Modal，关闭后再进同一页面，Modal点不动了；或者控制台报 Bootstrap's JavaScript requires jQuery（即使你没用jQuery）——其实是插件初始化失败后残留状态干扰了后续调用。
- 不要在
useEffect里只调用new bootstrap.Modal(...)就完事，必须手动销毁 - 销毁必须在清理函数中调用实例的
dispose()方法，不是hide()或删DOM节点 - 确保每次初始化都基于当前渲染的DOM节点，避免引用已卸载组件里的
ref.current
jQuery依赖冲突与ESM导入问题
Bootstrap 5+ 官方已移除jQuery依赖，但很多老项目或CDN链接仍混用v4（带jQuery）和v5（原生），或者开发者误用了需要jQuery的旧版文档示例。更隐蔽的问题是：通过 import * as bootstrap from 'bootstrap' 引入时，若未正确配置打包工具（如Webpack别名或exports字段），可能实际加载的是UMD版本，导致 bootstrap.Modal 是 undefined。
典型错误信息：TypeError: bootstrap.Modal is not a constructor，或控制台警告 Bootstrap dropdown require Popper（其实Popper已内置，但路径解析错了）。
- 确认安装的是Bootstrap 5.x：
npm list bootstrap，且版本 ≥ 5.0.0 - ESM导入必须用命名导入：
import { Modal } from 'bootstrap'，不能用默认导入或通配符 - 如果用Vite，需检查是否启用了
optimizeDeps.include: ['bootstrap']，否则Tree-shaking可能破坏内部模块链
事件委托与React事件系统不兼容
Bootstrap的 Tooltip 和 Popover 默认启用事件委托（靠document监听click/mouseenter），而React事件是合成事件，冒泡路径和原生事件不同步。结果就是：React里用 onClick 阻止冒泡，却拦不住Bootstrap的tooltip显示；或者tooltip显示后，点击空白处无法隐藏——因为 hide() 依赖的document级事件被React事件系统截断了。
使用场景：在表格行内放 Tooltip，鼠标移入触发，但移出后tooltip卡住不消失。
- 禁用委托模式：初始化时传
{ boundary: 'window', trigger: 'manual' }，改用显式show()/hide() - 绑定到React事件：用
onMouseEnter调tooltip.show()，onMouseLeave调tooltip.hide()，避免依赖document级监听 - 注意
delay参数是对象形式：{ show: 0, hide: 100 }，不是数字，否则tooltip会失效
SSR/服务端渲染下DOM不存在导致初始化失败
Next.js或Remix等框架服务端渲染时，document 和 window 未定义，任何直接调用 bootstrap.Modal 的代码都会抛 ReferenceError: document is not defined。即使加了 typeof window !== 'undefined' 判断，也可能因hydration时机不对，导致客户端首次渲染时插件未绑定。
性能影响：插件初始化逻辑若放在顶层或组件外，会阻塞服务端构建；若放在 useEffect 但没加依赖数组，可能每次渲染都重复初始化。
- 所有Bootstrap JS调用必须包裹在
useEffect中，且确保只在客户端执行 - 初始化前校验节点存在：
if (!ref.current) return，防止hydration时ref为空 - 避免在自定义Hook里直接返回实例（如
useModal(ref)），应返回操作函数，把实例生命周期完全交给组件管理
最易被忽略的一点：Bootstrap插件的 dispose() 不仅要清事件，还要清data属性（data-bs-* ）和aria标签——这些残留会影响后续同节点的重新初始化，尤其在列表项复用ref时。手动清理比依赖插件自带销毁更稳妥。
