z-index: var(--z-modal)无效的首要原因是元素未设非static定位；必须显式设为relative、absolute、fixed或sticky，否则变量不参与层叠计算，且变量须在顶层非scoped样式中定义才全局有效。
不是CSS变量帮不上忙，而是你没让它“上岗”——z-index: var(--z-modal) 写对了，但元素根本没资格参与层叠计算，变量再优雅也白搭。
元素没设 position，变量就等于没写
浏览器对 z-index 的处理极其严格：只要 position 是 static（默认值），整个声明就被忽略，连解析都不做。你在 DevTools 的「Computed」面板里看到 z-index 显示为 auto 或灰掉，就是这个信号。
- 常见漏写：
.modal { z-index: var(--z-modal); }—— 缺少position: fixed或relative - 动态插入的弹窗、Portal 挂载的内容，最容易只改
z-index，却忘了同步加定位 -
display: flex或grid容器里的子项，不会“继承”定位能力，必须自己声明position
父级悄悄建了 stacking context，变量值被锁死在小房间
即使 position 正确，z-index 也可能只在局部生效。只要某个祖先元素满足以下任一条件，就会创建独立的层叠上下文，把子元素的 z-index “关”在里面：
-
opacity小于 1（比如opacity: 0.99） -
transform不为none（包括看似无害的transform: translateZ(0)） -
filter、will-change、isolation: isolate
验证方法：在 Chrome DevTools 的 Elements 面板中逐级点击父节点，右侧面板「Layout」标签页下看「Stacking context」是否突然变成 Yes；临时注释掉可疑属性，遮挡消失就定位成功。
立即学习“前端免费学习笔记（深入）”；
:root 里定义了，但组件根本读不到
:root { --z-modal: 1000; } 不等于全局可用——作用域错了，变量就失效。
- 在
<style scoped>里写:root是无效的，scoped 会加属性选择器，把:root锁死在当前组件内 - Vue 项目必须写在
App.vue的非 scoped<style>块中；React 项目要写在index.css或全局样式入口 - UniApp 等跨端框架中，
uni.showToast渲染到<body>下，如果变量只定义在某个 page 文件里，它完全看不到 - 原生组件（如
uni-modal）class 名不固定，不能靠选择器注入，得靠顶层:root声明才兜得住
数值设计和 JS 交互时容易踩坑
变量本身是字符串，JS 读取后不做转换直接比较会出错；数值没留空档，后期扩容就撞上限。
-
getComputedStyle().getPropertyValue('--z-modal')返回的是字符串，用前必须parseInt() - 别写
var(--z-base, 10px)这种带单位的默认值——z-index只接受整数 - 避免
calc(var(--z-modal) + 1)：旧版 Safari 对calc+var()支持不稳定 - 别迷信
999999，32 位有符号整数上限是2147483647，溢出变负数，调试极难定位
真正卡住你的，往往不是变量写得对不对，而是 DOM 路径上某一层的 transform 或 opacity 悄悄把你关进了独立盒子——得往上翻三层祖先节点，挨个查「Stacking context」。
