z-index不生效需依次排查Sass变量、CSS层叠层、Portal渲染位置和层叠上下文；Bootstrap用$zindex-*变量统一控制，须在引入前覆盖，且注意@layer优先级、portal脱离DOM层级及iOS Safari的stacking context陷阱。
z-index 不生效？先查 $zindex-dropdown 这类 Sass 变量
bootstrap 的 z-index 不是散落在 css 里硬写的，而是统一由 sass 变量控制。如果你直接在 css 里写 .my-modal { z-index: 9999; } 却没效果，大概率是因为组件内部的层级依赖变量计算（比如 dropdown 用的是 $zindex-dropdown，modal 用的是 $zindex-modal），而你的样式被后加载的 bootstrap css 覆盖了。
实操建议：
- 打开 Bootstrap 源码里的
_variables.scss（v5.3 在scss/_variables.scss），搜索$zindex-，你会看到一整组预设值：$zindex-dropdown: 1000、$zindex-sticky: 1020、$zindex-fixed: 1030、$zindex-modal: 1055等 - 修改必须在引入 Bootstrap 样式前覆盖这些变量，例如在自定义 SCSS 中写：
$zindex-modal: 2000;<br>@import "bootstrap/scss/bootstrap";
- 别只改一个——如果 modal 里嵌 dropdown，而
$zindex-dropdown还是 1000，那下拉菜单会钻到 modal 背后
用 CSS 覆盖时，为什么加 !important 也不管用？
因为 Bootstrap v5 默认启用了 CSS 层叠层（@layer），所有组件样式都包裹在 @layer bootstrap 里，而普通 CSS 属于 @layer default，天然层级更低。即使你写了 z-index: 9999 !important，只要它不在同个 layer 或没更高 specificity，依然会被压住。
实操建议：
- 优先用
@layer对齐层级：@layer bootstrap-overrides {<br> .my-custom-modal { z-index: 2100; }<br>} - 如果不用 layer，就提高选择器 specificity：比如不用
.modal，改用body .modal.show或div.modal.fade.show -
!important是最后手段，且仅对单个声明有效；它无法提升整个规则块的权重，也不能解决 layer 隔离问题
React/Vue 项目里动态组件的 z-index 为什么乱套？
框架组件（如 react-bootstrap 的 Modal 或 vue-bootstrap 的 BModal）往往把 portal 到 body 底下，脱离原有 DOM 层级。这时它的 z-index 只跟 body 下其他 portal 元素比，跟你组件内部的 position: relative 容器完全无关。
实操建议：
- 检查组件是否用了 portal：React 中看是否渲染到
document.body；Vue 中看是否有teleport到body - 不要试图在父组件里调
z-index控制子组件的 portal 内容，得直接配该组件的zIndexprop（如<Modal zIndex={2000}>）或全局配置（如BootstrapVue.config.BOOTSTRAP_VUE_ZINDEX） - 多个 modal 嵌套时，确保它们的 z-index 值严格递增（比如 2000 → 2001 → 2002），别跳着设（1000 → 3000 → 2000）
移动端 Safari 上 z-index 突然失效？
这是老坑：iOS Safari 对 transform、opacity < 1、will-change 等属性敏感，一旦父元素触发了层叠上下文（stacking context），子元素的 z-index 就只在该上下文内生效，不再和 body 下其他元素比。
实操建议：
- 检查 modal 或 dropdown 的父容器有没有无意中加了
transform: translateZ(0)、opacity: 0.99之类——哪怕只是动画过渡残留 - 用 Safari 开发者工具的 “Layers” 面板（不是 Elements）看真实层叠结构，确认 modal 是否被意外包裹进某个 stacking context
- 临时加
backface-visibility: hidden有时能重置，但治标不治本；根本解法是移除触发 stacking context 的属性，或把 modal 提到更外层
z-index 看似简单，实际是变量、layer、portal、stacking context 四层机制咬合的结果。漏掉其中一层，就容易陷入“明明写了却无效”的循环。最稳妥的方式永远是：查变量 → 对 layer → 查渲染位置 → 排 stacking context。
