模态框背景遮罩未出现或半透明失效，本质是 Bootstrap 5 的 Modal JS 初始化失败导致 .modal-backdrop 未插入 DOM；需确认加载 bootstrap.bundle.min.js（含 Popper）、检查控制台报错、动态插入后手动初始化，并排查祖先元素的 transform/overflow 对 fixed 定位的影响。
模态框背景遮罩没出现或半透明失效
遮罩层（.modal-backdrop）不显示，通常不是 CSS 被覆盖，而是它根本没被插入 DOM。Bootstrap 5 的 Modal JS 初始化失败时，连 backdrop 元素都不会生成——你看到的只是静止的 .modal 容器，没有 overlay，也没有 fade 动画。
检查方式：点击触发按钮后，在 Elements 面板搜索 modal-backdrop；如果找不到，说明 JS 没跑起来。
- 确认已加载
bootstrap.bundle.min.js（含 Popper），不是bootstrap.min.js -
bootstrap.bundle.min.js必须在bootstrap.min.css之后、任何自定义 JS 之前引入 - 控制台报
Uncaught ReferenceError: bootstrap is not defined→ JS 文件路径错或 404 - 页面动态插入模态框 HTML 后，未手动调用
new bootstrap.Modal(...)
模态框内容区域错位、高度塌陷或边框消失
常见现象是 .modal-content 看起来“缩进”、“压扁”或边框只剩上边一条线。这几乎总是因为父容器设置了 overflow: hidden 或 transform，导致 .modal 的定位上下文被截断或重置。
Bootstrap 5 的 .modal 默认使用 position: fixed，但一旦祖先元素有 transform、filter 或 will-change，就会创建新的层叠上下文，使 fixed 失效，退化为 relative 定位。
立即学习“前端免费学习笔记（深入）”；
- 检查
.modal直接父级及所有向上祖先的 computed 样式，重点看transform和overflow - 若页面根容器（如
#app）有transform: scale(0.95)，必须把.modal移出该容器，或改用data-bs-container="body" -
.modal-dialog内部必须严格套.modal-content→.modal-header/.modal-body/.modal-footer，缺一不可，否则 flex 布局断裂
关闭按钮（X）不显示或点击无效
关闭按钮消失，大概率是用了 × 实体但没配对 .btn-close 类，或者类名拼错成 .close（这是 Bootstrap 4 写法，v5 已废弃）。
即使按钮可见，点击无响应，往往是因为 data-bs-dismiss="modal" 属性缺失或写成了旧版 data-dismiss。
- 正确写法：
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> - 不要用
<span aria-hidden="true">×</span>手动模拟，v5 的.btn-close是 SVG + 伪元素实现，依赖 CSS 变量控制颜色和尺寸 - 如果自定义了
--bs-btn-close-color，确保它不是透明色或与背景同色
模态框弹出后页面内容被推移（非预期滚动/位移）
这不是样式“异常”，而是 Bootstrap 5 默认启用 data-bs-scroll="false"（即禁用 body 滚动）时，会往 <body> 加 padding-right 补偿滚动条宽度。但如果页面本身有横向滚动条、或你手动给 body 设了 overflow-x: hidden，这个补偿就失效，导致右侧内容被挤偏。
- 最稳解法：显式设置
<body class="modal-open">并配 CSSbody.modal-open { padding-right: 0 !important; }（慎用!important，仅用于覆盖 Bootstrap 内联 style） - 更推荐：在初始化 Modal 时传参
{ scroll: true }，关闭 padding 补偿，改用overflow: hidden锁定 body - 避免在
.modal外层再套position: relative容器——它会干扰fixed定位锚点
bootstrap.min.css 完全正常，只要 bootstrap.bundle.min.js 加载失败或初始化中断，你就只会看到一堆“静态 HTML”，所有定位、动画、遮罩、滚动锁定都会消失——这时调样式毫无意义。 
