z-index必须配合position生效，且易被父级层叠上下文限制；弹窗被遮盖主因是position为static或父容器创建新层叠上下文；应统一用CSS变量管理层级，并确保遮罩与内容同属一个上下文。
z-index 不是写个大数字就能让弹窗“永远在最上”，它必须配合 position 生效，且极易被父级层叠上下文锁死——这是新手踩坑最多的地方。
为什么弹窗写了 z-index 却被遮住？
常见现象：弹窗容器设了 z-index: 9999，但依然被导航栏、轮播图或卡片盖住。根本原因不是值不够大，而是它没真正“入场”：
- 目标弹窗元素的
position仍是static（默认值），z-index被浏览器直接忽略 - 弹窗父容器加了
transform: translateY(0)或opacity: 0.99，悄悄创建了新层叠上下文，把弹窗“关”在里面 - 遮罩层（
.mask）和弹窗内容（.popup）不在同一层叠上下文中，比如一个在.header内，一个在.main内，它们的z-index根本不比大小
调试时打开 Chrome DevTools 的「Layers」面板，或在「Computed」里看目标元素的 z-index 是否显示为具体数值（而非 auto）和 position 是否生效。
弹窗结构中 z-index 怎么分层才不打架？
遮罩层和弹窗内容必须同属一个层叠上下文，且层级分明。典型可靠结构如下：
立即学习“前端免费学习笔记（深入）”；
.modal {
position: fixed;
top: 0; left: 0;
width: 100%; height: 100%;
z-index: var(--z-modal-overlay, 1000); /* 遮罩层基准 */
}
<p>.modal__mask {
position: absolute;
top: 0; left: 0;
width: 100%; height: 100%;
background: rgba(0,0,0,0.5);
z-index: 1; /<em> 相对 .modal 内部计数 </em>/
}</p><p>.modal<strong>content {
position: relative;
z-index: 2; /* 必须高于 .modal</strong>mask */
}
关键点：
-
.modal用fixed定位并设基础z-index，让它脱离原有文档流上下文 -
.modal__mask和.modal__content都在.modal内部，靠相对值（1/2）控制彼此顺序 - 避免给
.modal__content内部按钮、标题等再设高z-index，否则容易自己把自己挡住
如何用 CSS 变量统一管理弹窗层级？
直接写死 z-index: 1000 很快会失控。正确做法是在项目顶层非 scoped 样式中定义变量：
:root {
--z-toast: 800;
--z-dropdown: 900;
--z-modal-overlay: 1000;
--z-modal-content: 1001;
--z-fullscreen: 1500;
}
然后组件内使用：
.modal {
z-index: var(--z-modal-overlay);
}
<p>.modal__content {
z-index: var(--z-modal-content);
}
注意：
- 变量必须定义在全局样式（如
App.vue的顶层<style>或index.css），<style scoped>里定义的:root无效 - 数值之间留出空档（如
1000→1001），方便后续插入中间层级（比如加个带动画的过渡层） - 不要在 JS 中直接比较
getComputedStyle(...).getPropertyValue('--z-modal')返回的字符串，要先parseInt()
什么时候该放弃 z-index，直接提 DOM？
当弹窗嵌套太深、父容器又无法修改（比如第三方 UI 库内部结构），或反复调 z-index 仍无效时，最简单可靠的方案是：用 JS 把弹窗节点动态 appendChild 到 document.body 下。
这样做天然脱离所有原有层叠上下文，只靠 DOM 顺序和自身 z-index 就能稳居顶层。但要注意同步位置（比如用 getBoundingClientRect() 计算偏移）和事件代理（因为 DOM 移动后原绑定可能失效）。
真正难的从来不是数字填多大，而是发现哪个 transform 或 opacity 正在无声地把你精心写的 z-index 关进小黑屋。
