<p>Popper v1 与 Bootstrap 5 不兼容，因后者强制要求 @popperjs/core@^2.0.0；混用会导致下拉菜单等组件报错或失效；需改用 data-bs-* 属性并手动初始化动态插入的 Popper 实例。</p>
Popper v1 与 Bootstrap 5 的兼容性断裂是硬性限制
Bootstrap 5 明确要求使用 @popperjs/core@^2.0.0，不支持旧版 popper.js@^1.x。这不是配置问题，而是 API 层面的彻底重构：v1 的 positionFixed、gpuAcceleration 等选项在 v2 中已被移除或重命名；v2 改用 strategy: 'fixed' 和 adaptive: false 等新字段，且内部坐标计算逻辑完全重写。一旦混用，下拉菜单、Tooltip、Popover 会直接报错 cannot read properties of undefined (reading 'getboundingclientrect') 或静默失效。
bootstrap.min.js 和 bootstrap.bundle.min.js 的 Popper 内置差异
Bootstrap 5 的 bootstrap.min.js 已内置 @popperjs/core v2，而 bootstrap.bundle.min.js 是它的“全量版”，二者都含 Popper，但不能共存。常见错误是同时引入：
- 只引入
bootstrap.min.js却手动再加@popperjs/corev1 → 冲突 - 引入
bootstrap.bundle.min.js后又额外加载popper.js@1.x→ 控制台报Popper: "reference" is not a valid selector - 用模块化方式（如 ES import）却写成
import Popper from 'popper.js'→ 应为import { createPopper } from '@popperjs/core'
data 属性升级不彻底导致 Popper 组件“假激活”
即使 JS 加载正确，如果 HTML 还保留 Bootstrap 4 的 data-toggle="dropdown"，Bootstrap 5 的 Dropdown 类根本不会初始化 Popper 实例——它只响应 data-bs-toggle="dropdown"。结果就是点击有反馈，菜单 DOM 渲染出来了，但位置固定在左上角、不随滚动更新、溢出视口，因为 Popper 根本没启动。
其他组件同理：
-
data-target="#modal"→ 必须改为data-bs-target="#modal" -
data-dismiss="modal"→ 必须改为data-bs-dismiss="modal" - 所有
data-*都要加bs-命名空间，否则 JS 不识别
动态插入 DOM 后 Popper 实例未重建
用 innerHTML 或 appendChild 插入带 data-bs-toggle="dropdown" 的按钮后，Bootstrap 不会自动扫描并初始化新元素。菜单能点开，但定位异常或完全错位，因为 Popper 实例仍绑定在旧节点或压根没创建。
修复方式不是重新引入 JS，而是手动触发：
- 获取元素：
const dropdownEl = document.querySelector('#myDropdown') - 创建实例：
new bootstrap.Dropdown(dropdownEl) - 或复用已有实例：
bootstrap.Dropdown.getInstance(dropdownEl)?.toggle()
这个步骤容易被忽略，尤其在单页应用（SPA）或 tab 切换场景中——它不是“一次引入就万事大吉”的机制。
最常被漏掉的是命名空间迁移和动态 DOM 初始化，这两处一错，Popper 就等于没装。
