最常见原因是模态框根元素未写class="modal fade"，必须直接写在上；动画仅作用于.modal.fade .modal-dialog选择器链，需同时定义初始态（transform: translatey(100%)、opacity: 0）和显示态（transform: translatey(0)、opacity: 1），显式声明transition属性，同步处理.modal-backdrop。
为什么加了 fade 类还是硬切
最常见原因是模态框根元素没写 fade 类：class="modal fade" 必须直接写在最外层 <div class="modal"> 上，不是 <code>.modal-dialog，也不是靠 data-bs-fade 属性触发。Bootstrap 5 的 JS 只认 class 名匹配，只负责加/删 show，不解析任何 data 属性。
.modal.fade .modal-dialog 初始态和目标态怎么写
动画只作用于这个选择器链，其他地方加 transition 都无效。必须同时定义初始隐藏态和显示态：
-
.modal.fade .modal-dialog：设transform: translateY(100%)+opacity: 0 -
.modal.fade.show .modal-dialog：设transform: translateY(0)+opacity: 1 - 别用
scale(0.95)等默认值干扰位移——显式覆盖为transform: translateY(100%) scale(1) - 过渡属性必须明确列出：
transition: transform 0.3s cubic-bezier(0.22, 0.61, 0.36, 1), opacity 0.3s ease-out，不能写all
.modal-backdrop 动画不同步怎么办
弹窗有动画但遮罩“啪”一下闪出来，大概率是 backdrop 没同步改。它和 modal 主体的过渡时长、触发时机必须一致：
-
.modal.fade .modal-backdrop要加transition: opacity 0.3s ease-out -
.modal.fade.show .modal-backdrop保持opacity: 1即可，不用改transform - 如果禁用 backdrop 动画，设
.modal-backdrop.fade { transition: none }，但别只改.show状态
自定义动画时容易被忽略的细节
真正生效的不是“加个类”或“调个函数”，而是 CSS 规则是否精准命中且无冲突：
- 必须保留
fade类，否则 JS 不会触发动画流程，transition再全也白搭 - 不要用
!important盲目覆盖，优先提高选择器权重（比如加.my-modal前缀） - Safari 下
transition: all容易导致闪烁，老版本还可能把z-index或display也纳入过渡 - 动态插入的模态框，需确保 DOM 插入后、调用
modal('show')前，HTML 结构已含modal fade
