modal-dialog-centered类必须加在.modal-dialog元素上才生效，加在.modal或.modal-content上无效；其依赖.modal-dialog的position: relative和transform: translate(-50%, -50%)实现垂直居中。
modal-dialog-centered类加在哪才生效
必须加在.modal-dialog元素上，不是.modal，也不是.modal-content。Bootstrap 5 的垂直居中逻辑只认这个位置——它依赖.modal-dialog的position: relative和内置的transform: translate(-50%, -50%)计算。加错地方等于没加。
常见错误写法：<div class="modal modal-dialog-centered"> 或 <code><div class="modal-content modal-dialog-centered">，这两种都无效，浏览器开发者工具里能看到<code>transform根本没被应用。
用了fade动画还手动重置margin-top就偏了
.modal.fade .modal-dialog在动画初始阶段会被设为margin-top: -200px（或类似值），这是滑入效果的基础。如果你在自定义 CSS 里写了.modal-dialog { margin-top: 0 }或带!important的覆盖，就会和modal-dialog-centered的transform冲突，导致最终位置上浮或抖动。
检查方式：打开 DevTools → Elements → 找到.modal-dialog → 看“Computed”里的margin-top是否还是负值。如果不是，说明被你覆盖了。
- 别全局重置
.modal-dialog的margin - 如需微调起始高度，改
transition时长或用show.bs.modal事件延迟操作 - 真要动位置，优先用
shown.bs.modal事件，等动画完成后再触发
动态创建模态框时DOM没挂载就调show()
JS拼HTML后直接$('body').append(modalHtml).find('.modal').modal('show')，容易失败。因为modal-dialog-centered的transform虽不依赖尺寸，但内部滚动锁定、backdrop高度计算等会在show()前读取.modal-dialog的offsetHeight——此时若还没挂进 DOM，值为 0，Safari 下尤其容易错位或键盘弹出异常。
正确顺序：
- 先
$('body').append(modalHtml) - 再用
requestAnimationFrame(() => $('#myModal').modal('show'))或setTimeout(() => ..., 0) - 更稳妥：监听
shown.bs.modal，而不是show.bs.modal
父容器干扰flex布局导致整体偏移
.modal变成display: flex后，如果它内部有非.modal-dialog的子节点（比如注释、空文本、动态插入的占位符），也会被当作 flex item 参与排列，把.modal-dialog挤偏。
另外，某些老项目 CSS 会写body.modal-open { position: absolute }，这会破坏 flex 流式布局；还有人给.modal加overflow: hidden以外的定位属性，也会干扰对齐。
排查建议：
- 用 DevTools 检查
.modal的 computeddisplay是否真为flex - 看
.modal下有没有多余子节点（右键 → “Edit as HTML”快速清理） - 搜索全局 CSS，删掉所有对
.modal或body.modal-open的position覆盖
真正麻烦的不是写几行 CSS，而是这些隐藏的 DOM 结构和样式污染——它们不会报错，只会让居中看起来“偶尔不准”。
