Bootstrap 5 模态框垂直居中唯一可靠方案是将 modal-dialog-centered 类加在 .modal-dialog 元素上，依赖 .modal 的 display: flex 布局和内部 top: 50% + transform 组合，加错位置或结构不完整均失效。
Bootstrap 5 模态框默认不垂直居中，只加 modal-dialog-centered 类就能解决——但必须加在 .modal-dialog 上，加错位置就完全无效。
modal-dialog-centered 是唯一可靠方案
Bootstrap 5 官方明确将垂直居中逻辑封装在 modal-dialog-centered 这个工具类里，它内部组合了 top: 50% 和 transform: translate(-50%, -50%)，并依赖 .modal 的 display: flex 布局。这不是“可选优化”，而是框架设计的唯一正向路径。
- 必须加在
<div class="modal-dialog">元素上，加在.modal或.modal-content上毫无作用 - 不能省略基础类
modal-dialog，否则modal-dialog-centered的样式规则不会被匹配 - 该类天然适配响应式、缩放、横竖屏切换，无需监听
resize或手动重算 - 移动端 Safari 下若内容动态加载导致偏移，只需确保 DOM 渲染完成后再调用
show()，不需额外 hack
为什么手动写 transform 或 flex 不推荐
直接给 .modal-dialog 加 transform: translate(-50%, -50%) 看似简单，但极易失效——因为 .modal-dialog 默认是 position: relative，而 transform 不改变定位上下文，单独使用无法锚定到视口中心。
- 漏掉
top: 50%或父容器没触发 flex 布局（如.modal被其他 CSS 覆盖了display: flex），transform就只是“原地位移” - 用
d-flex align-items-center类试图影响.modal-dialog：无效，因为.modal-dialog是绝对定位元素，flex 属性对其父级.modal的子项布局无约束力 - 靠
mt-5或margin-top手动推：响应式下会错位，内容高度变化时立刻失准 - 混用 Bootstrap 4 的旧 CSS（如
top: 50% + transform）和 Bootstrap 5 的 flex 布局，反而引发冲突
动态创建模态框时的常见坑
用 JS 动态生成 .modal 结构再调用 show() 时，如果 DOM 还没挂载完成或样式未计算，modal-dialog-centered 可能不生效，表现为模态框仍贴顶。
立即学习“前端免费学习笔记（深入）”；
- 确保模态框 HTML 已插入 document（例如用
document.body.appendChild(modalEl)），再调用new bootstrap.Modal(modalEl).show() - 不要在
show()后立即读取.modal-dialog高度来手动计算 top——modal-dialog-centered本身已处理了这个逻辑 - 若内容含异步加载（如图片、远程表单），可在
shown.bs.modal事件中检查是否居中；未居中说明结构有误（比如类名拼错或嵌套层级错） - IE11 不支持
modal-dialog-centered（因依赖transform+flex），需单独提供回退样式，但 2026 年绝大多数项目已无需兼容
真正容易被忽略的是：modal-dialog-centered 的生效前提不是“写了这个类”，而是整个模态框结构完整且未被第三方 CSS 干扰。哪怕只是多了一个 body { position: relative }，都可能破坏 .modal 的 flex 容器行为。验证方式很简单——打开开发者工具，看 .modal 元素是否计算出 display: flex 和 align-items: center。没有，就先查样式覆盖源。
