Bootstrap 5 必须为 .modal-dialog 添加 modal-dialog-centered 类才能垂直居中，因其默认仅水平居中、垂直靠顶；该类通过 top: 50% 与 transform: translate(-50%, -50%) 实现可靠居中，适配滚动、缩放及横屏。
Bootstrap 5 必须加 modal-dialog-centered 类
Bootstrap 5 的 .modal 默认只水平居中，垂直方向是顶部对齐——不是 bug，是设计如此。不加这个类，.modal-dialog 就不会垂直居中。
它依赖父级 .modal 的 flex 布局（Bootstrap 5 已内置 display: flex），内部用 transform: translate(-50%, -50%) 实现，天然适配滚动条、缩放、横屏切换等场景。
- ✅ 正确写法：
<div class="modal-dialog modal-dialog-centered"> - ❌ 不要加在
.modal或.modal-content上，只对.modal-dialog生效 - ⚠️ 如果用了
fade动画，检查是否手动覆盖了.modal.fade .modal-dialog的margin-top，会和 transform 冲突 - ⚠️ 动态创建模态框（比如 JS 拼 HTML 后
append）时，必须先挂载到 DOM，再调用modal('show')，否则offsetHeight读不到真实尺寸，transform 计算失准
Bootstrap 4 没有 modal-dialog-centered，得手动补 CSS 或 JS
Bootstrap 4 默认用 display: table-cell + vertical-align: middle 实现垂直居中，理论上应该居中。但实际偏上，大概率是以下原因：
- 外层容器写了
position: relative或transform，干扰了模态框的定位上下文 -
modal('show')调用太早，DOM 还没 ready，导致高度计算为 0 - 漏了
modal-dialog-centered？别急——它在 v4 里根本不存在，是 v5 才加的
稳妥做法是加一段轻量 CSS：
.modal-dialog {
margin: 0 auto;
position: relative;
top: 50%;
transform: translateY(-50%);
}
.modal {
padding: 0 !important;
}
注意：不要给 .modal 加 overflow: hidden，否则 transform 向上偏移的部分会被裁掉。
动态内容加载后模态框偏移，比如 AJAX 或图片
模态框打开时内容为空或高度为 0（例如富文本、CodeMirror、未加载的图片），等数据回来、图片渲染完成，高度突然变大，但 .modal-dialog 并不会自动重算位置。
- 监听
shown.bs.modal（不是show.bs.modal），确保 DOM 渲染完毕、尺寸可读 - 如果内容是异步加载的，得在加载完成回调里手动触发一次居中逻辑，比如重新设
transform或触发布局重排 - 更省事的办法：给
.modal-dialog加modal-dialog-scrollable类，让内容区可滚动，避免撑高后错位 - 移动端 Safari 需额外监听
resize事件，因为键盘弹出/收起会触发视口变化，但不触发shown回调
自定义样式覆盖了居中行为，怎么排查
最常见的“加了类却没反应”，往往是因为某处 CSS 意外覆盖了关键声明：
- 检查是否给
.modal-dialog写了position: absolute、top、margin-top或transform—— 这些会直接干掉modal-dialog-centered的 transform - 检查是否给
.modal加了height: 100%或min-height: 100%：这会让 flex 容器失去“可用交叉轴空间”，align-items: center失效；应改用min-height: 100vh - 检查是否在
body或html上加了overflow: hidden或position: fixed，会切断模态框的定位流 - 用浏览器 DevTools 直接看
.modal-dialog元素的 computedtransform值：如果是none，说明类没生效或被覆盖；如果是translate(-50%, -50%)但位置不对，说明参考系错了（比如父容器没 flex）
真正容易被忽略的是：模态框是否在某个 position: relative 的 wrapper 里被嵌套了——这种布局下，transform 的参考系会变成那个 wrapper，而不是视口。
