本文围绕 CSS z-index失效？弹出框为何会被遮挡：从堆叠上下文到定位、变换的全面排查与解决，展开系统性的分析。
1. 堆叠上下文基础
在现代浏览器的渲染流程中，堆叠上下文决定了同一层级内的元素谁在前、谁在后。z-index只有在有定位（非静态定位）的元素上才会生效，且其数值大小决定了相对于同一堆叠上下文中其它元素的前后顺序。根堆叠上下文通常由文档树根元素及特定属性触发，而子元素的层级必须在父上下文范围内进行比较。
如果一个弹出框被放置在一个会创建新堆叠上下文的父容器中，即便它在文档流中处于较后的位置，也可能被同级或兄弟节点以更高的堆叠级别覆盖。这就解释了为何仅仅依赖 输送顺序（DOM 顺序） 并不足以保证弹出框始终显示在最前端。
下面的示例用来说明两种场景：一是父容器未创建新堆叠上下文，弹出框自由覆盖；二是父容器创建了新的堆叠上下文，弹出框被限制在容器内。你可以通过调换弹出框的父节点来验证效果。
/* 场景 A：弹出框在 body 下，无额外堆叠上下文 */
.modal { position: fixed; top: 20px; left: 50%; transform: translateX(-50%); z-index: 1000; }/* 场景 B：弹出框在一个新堆叠上下文的父容器内 */
.panel { position: relative; z-index: 1; opacity: 0.99; } /* 会创建新的堆叠上下文 */
.dialog { position: absolute; z-index: 2000; }
总结要点：理解不同父级是否会创建新的堆叠上下文，是解决弹出框被遮挡的第一步。
2. 定位对弹出框的影响
2.1 定位模型与层级关系
定位是影响弹出框层级的关键因素。固定定位（fixed）和绝对定位（absolute）都属于可参与堆叠上下文的定位类型，但它们对层级的影响由其所在父容器的堆叠上下文决定。仅当目标元素在可比较的同一堆叠上下文中时，z-index才会生效。
若弹出框的父容器拥有较高的 z-index，而且该父容器自身又处于一个新的堆叠上下文内，则弹出框的可见性就必须通过改变父容器的层级来实现。此时单独提高弹出框的 z-index 可能不起作用，因为它仍然被父容器的层级约束。
要测试这类问题，可以先把弹出框直接移到 body 之下，确保它不再受父容器的堆叠上下文限制。若弹出框显现，需要检查原父容器及其祖先元素的定位和透明度等属性。
/* 将弹出框从受限父容器中移到 body 下进行对比 */
弹出框
2.2 遮罩层与弹出框的叠层关系
常见的遮罩层（ backdrop ）通常使用 position: fixed 或 absolute 配合全屏尺寸来覆盖页面。若遮罩层的 z-index 高于弹出框，遮罩自然会把弹出框遮挡在下方。此时需要确保弹出框的 z-index 足够大且位于同一层级或更高层级，且遮罩层不再阻挡。
为确保可控性，可以设置弹出框在覆盖遮罩之上的显式层级：z-index 的值应高于遮罩层，并且遮罩层的层级应与弹出框的容器结构相匹配。
下面的代码演示一个常见的遮罩与弹出框的对比结构：遮罩先覆盖页面，弹出框再置于更高层级。
.backdrop { position: fixed; top: 0; left: 0; width: 100%; height: 100%; z-index: 999; }
.modal { position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); z-index: 1001; }
3. 变换与新建堆叠上下文的关系
3.1 变换创建的新堆叠上下文
浏览器在检测到 transform、perspective、filter、opacity 等属性时，可能会在元素上创建一个新的 堆叠上下文，从而影响弹出框的显示顺序。即使弹出框的 DOM 顺序在前，若父容器或同级元素创建了新的上下文，弹出框仍可能被限制在该上下文内。
对于具有 opacity 小于 1 的父元素，甚至在视觉上看起来透明，其内部的子元素仍然被限制在该父上下文中，弹出框的层级就会受限。因此，谨慎使用低透明度的父容器以及需要跨上下文显示的弹出框。
要验证是否存在新堆叠上下文，可以使用浏览器开发者工具的“层级”视图，检查哪一个父元素在创建新的上下文，以及弹出框处于哪个上下文中。
/* 变换属性创建新堆叠上下文示例 */
.container { position: relative; transform: translateZ(0); } /* 新堆叠上下文 */
.dialog { position: fixed; z-index: 1000; }
4. 弹出框被遮挡的常见场景与排查步骤
4.1 常见场景
最常见的原因包括：父级元素创建新堆叠上下文、父级或同级元素设置了高 z-index、遮罩层覆盖在弹出框上方、弹出框所在容器使用了 overflow: hidden 或其它裁切属性，以及 Transform/Opacity 等会触发新上下文的属性。
在实际页面中，若你发现弹出框不能弹出到页面顶层，首要步骤是确认弹出框所在的具体上下文，以及该上下文及其祖先节点的定位、尺寸、以及裁剪属性。
/* 快速排查模板 */
.parent { position: relative; z-index: 1; overflow: hidden; } /* 可能裁切子元素 */
.modal { position: fixed; z-index: 9999; }
4.2 排查步骤要点
逐级检查父节点的定位与堆叠上下文，确认弹出框是否被父容器的上下文限制；若有必要，将弹出框直接放到 body 级别，测试是否仍受阻。
核对所有涉及的 z-index，确保弹出框的 z-index 高于遮罩层和其他潜在的覆盖元素；同时避免跨上下文比较时的误解。
检查 transform、opacity、filter、perspective 等属性是否在父节点或祖先节点上被应用，这些属性会创建新的堆叠上下文，影响显示顺序。
5. 从页面结构到样式的具体排查清单
5.1 检查父级遮罩层
当页面存在全屏遮罩层时，务必确保弹出框的 z-index足以覆盖遮罩层；如果遮罩层在同一父上下文内，直接提升弹出框的层级通常可解决问题。
此外，遮罩层的创建时机也很关键，若遮罩是在弹出框出现之前动态添加，确保弹出框在添加遮罩后仍具备最高层级。
5.2 检查 z-index 的有效性与层级
请确保 所有相关元素的 z-index 值在同一上下文中可比，避免在不同上下文之间进行盲目比较。若某些元素被放在了新的堆叠上下文中，单独提升弹出框的 z-index 可能没有效果。
建议在设计阶段就给弹出框分配一个稳定的层级，并结合遮罩层一同管理，确保用户体验的连贯性。
/* 常用的稳定层级方案示例 */
.modal-backdrop { position: fixed; inset: 0; z-index: 1000; }
.modal-dialog { position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); z-index: 1001; }
5.3 在新的上下文中的定位策略
如果页面结构需要在特定区域内显示弹出框，而该区域会形成新的堆叠上下文，考虑以下策略：将弹出框提升到与该上下文同级别的外部容器或直接放置在 body 层级；或者重新组织结构，使弹出框不被父容器的上下文限制。
在实现时，请优先采用可维护且对移动端友好的定位方式，并在多设备上进行可视性测试，以确保弹出框始终可见且可交互。
本文对 CSS z-index失效？弹出框为何会被遮挡：从堆叠上下文到定位、变换的全面排查与解决 这一话题进行了系统性梳理，涵盖了堆叠上下文、定位模型、变换导致的新上下文、遮罩层管理以及具体排查清单等关键内容。
