必须同时设置max-height（如calc(100vh - 200px)）、overflow-y: auto和-webkit-overflow-scrolling: touch于.modal-body，缺一则滚动不生效；父容器不得设height/max-height或overflow:hidden，否则截断滚动上下文。
modal-body 没设 max-height，滚动根本不会触发
浏览器判断是否显示滚动条，不是看内容多不多，而是看容器有没有“可溢出的高度边界”。.modal-body 默认没有任何高度限制，overflow-y: auto 单独写上去等于没写——它需要 max-height（或 height）来划定截断线。
常见错误现象：
- 加了
overflow-y: auto但滚动条不出现 - 内容撑开整个模态框，页面
出现全局滚动条
必须同时满足：
-
max-height要显式设置，推荐max-height: calc(100vh - 200px)（减去 header、footer、padding 实测总和），比70vh更稳，尤其在 iOS Safari 地址栏收放时不会抽搐 -
overflow-y: auto写在.modal-body上，不是.modal或.modal-content - 别给
.modal-dialog或.modal-content加height: 100%，会破坏弹性布局和垂直居中
用了 modal-dialog-scrollable 还是不滚？它只“启用逻辑”，不保“高度可用”
modal-dialog-scrollable 是 Bootstrap 5.2+ 提供的快捷类，但它只是 CSS 规则集合：自动给 .modal-body 加 max-height: calc(100vh - 1rem) 和 overflow-y: auto。一旦外部样式干扰高度继承，它就失效。
典型破坏场景：
-
.modal-dialog被意外设了flex: 1或height: 100% -
.modal-body里用了display: flex; flex-direction: column，但子元素没设flex: 1，导致高度塌陷 - 异步加载内容后，
max-height值不够用，但没动态更新 - DOM 结构被框架（如 Vue/React）替换，
.modal-body实际不存在或为空
建议做法：
- 直接在 HTML 中给
.modal-body加内联样式：style="max-height: calc(100vh - 200px); overflow-y: auto;" - 移动端务必补上：
-webkit-overflow-scrolling: touch - 用 DevTools 检查渲染后的
.modal-body是否真有内容、是否被display: none或visibility: hidden覆盖
iOS Safari 滚不动或卡顿，缺 -webkit-overflow-scrolling: touch
这不是 Bug，是 WebKit 渲染机制限制：即使 max-height 和 overflow-y: auto 都对，iOS Safari 默认禁用惯性滚动，导致拖动生硬、松手即停、甚至完全无响应。
关键点：
- 该属性**必须写在真正滚动的元素上**，也就是
.modal-body，写在.modal或.modal-content上无效 - 它只对 WebKit 内核生效（Chrome/Safari/Edge），Firefox 不需要也不识别
- 第三方滚动库（如
overlay-scrollbars）会接管原生滚动，此时该属性被绕过 - 某些富文本组件（如 Quill）初始化时可能重置
.modal-body的样式，需在shown.bs.modal后用 JS 补上：modalBody.style.webkitOverflowScrolling = 'touch'
滚动后点不到 backdrop 关闭模态框？z-index 错乱了
这不是滚动本身的问题，而是滚动启用后，某些子元素（如下拉菜单、autofocus 输入框、富文本编辑器）获得焦点并被 JS 临时提升 z-index，盖住了默认 z-index: 1040 的 .modal-backdrop。
排查方向：
- 检查
.modal-body或其直系子元素是否写了position: relative+z-index，删掉 - 确认第三方组件（如
vue-select、flatpickr）没在内部偷偷改z-index - 避免在
.modal-body内使用position: fixed元素，改用position: absolute并确保父容器有position: relative
最易被忽略的一点：所有这些样式和 JS 行为，都依赖 .modal-body 是真正的滚动容器。一旦结构错位、高度计算崩坏、或被框架动态移除，上面所有设置都会静默失效。
