CSS变量可管理z-index，但必须配合position属性并明确层叠上下文边界；否则变量再规范也无效。常见失效原因包括元素position为static、变量作用域受限、父容器触发新层叠上下文等。
z-index 能用 CSS 变量管理，但变量本身不解决层级逻辑混乱问题——真正起作用的是你如何定义、隔离和约束这些变量的使用边界。
为什么直接在 :root 里塞一堆 --z-modal、--z-toast 会出事
全局声明看似方便，实则把所有组件绑在同一根绳上。一个弹窗升级 --z-modal 到 1200，侧边栏菜单（也依赖这个变量）就可能意外浮到顶部，盖住用户正在操作的表单。
- 变量没“语义”，只有数值：别人看到
--z-modal: 1000，无法判断它是否包含遮罩层、内容层、箭头层 - 没有预留空档：如果
--z-dropdown是999，--z-modal是1000，后续加个中间层（比如带动画过渡的半模态框）就只能硬挤或改已有值 - 第三方库冲突：Ant Design 默认
--z-index-modal是1000，你设成1001，结果它的遮罩层用内联样式写死z-index: 1000，你的内容层反而被盖住
推荐的变量结构：基数 + 功能域 + 微调
不追求“一套变量打天下”，而是分层建模：
-
:root只放基础基数：--z-base: 0、--z-layer-1: 10、--z-layer-2: 100、--z-layer-3: 1000 - 功能组件就近声明语义化变量：
.modal { --z-element: calc(var(--z-layer-3) + 0); }、.modal__overlay { z-index: var(--z-element); }、.modal__content { z-index: calc(var(--z-element) + 10); } - 避免嵌套
calc(var(...) + ...)：旧版 Safari 对calc(var(--z-base) + 100)支持不稳定，建议只在 :root 层做一次计算，组件内直取var(--z-modal-overlay)
UniApp / Vue 单文件组件中变量失效的典型原因
你在 Page.vue 的 <style scoped> 里写了 :root { --z-toast: 1100; }，但 uni.showToast 弹出来的 DOM 在 <body> 下，根本读不到这个作用域。
-
:root声明必须在非scoped的全局样式中，UniApp 推荐放在App.vue的顶层<style>块 - 原生组件（如
uni-modal）不暴露 class 名，不能靠.uni-modal选择器注入样式；得用属性选择器，例如：[data-type="toast"] { z-index: var(--z-toast) !important; position: relative; } - 传入
customStyle是最可控的方式：uni.showModal({ customStyle: 'z-index: var(--z-modal); position: relative;' })
调试时最容易忽略的三层陷阱
写了 z-index: var(--z-modal) 却没效果？别急着改变量值，先看这三处：
立即学习“前端免费学习笔记（深入）”；
- 目标元素
position是static吗？浏览器会直接忽略它的z-index，哪怕变量值是对的 - 它的某个父级有
opacity: 0.99、transform: translateZ(0)或filter: blur(1px)吗？这些都会悄悄创建新层叠上下文，把它锁死在局部层级里 - 它的祖先容器有没有设
z-index？如果有，且值比兄弟容器低，那整个子树再高的z-index也出不去
Chrome DevTools 的「Layers」面板能直观显示层叠上下文边界，比反复猜更可靠。真正难的不是让变量生效，而是时刻意识到：z-index 不是数字游戏，它是定位、上下文、作用域共同作用的结果。
