CSS变量能管z-index，但需配合非static定位及明确层叠上下文边界；否则变量无效。90%失效源于元素未设relative/absolute/fixed/sticky定位，导致z-index被忽略；变量须在顶层非scoped样式中定义于:root才全局生效；跨模块应避免复用同名变量，数值预留间隙，并警惕父容器创建新层叠上下文。
直接说结论：CSS变量能管z-index，但必须配合非static定位 + 明确层叠上下文边界，否则变量再规范也白设。
z-index: var(--z-modal)写了却没用？先看元素有没有定位
写了变量但层级不生效，90% 是因为目标元素压根没资格参与层叠。position: static（默认值）下，z-index完全被忽略。必须显式设为relative、absolute、fixed或sticky才能激活。
- 检查开发者工具「Computed」面板：
z-index显示为auto或灰掉，说明没生效；position值不是上述四种之一，就是根本原因 - 常见误操作：只在父容器设
position: relative，子元素没设定位，z-index白写 - 第三方组件（如
uni-modal）挂载到<body>下，但<body>没设position，导致挂载后失去统一调度基准
:root里定义--z-modal不等于全局可用
变量声明位置不对，组件就根本读不到。在某个<style scoped>里写:root { --z-modal: 1000; }是无效的——scoped样式会加属性选择器，:root被限定在当前组件作用域内。
- 真正全局生效的写法，只有一处：在项目顶层非
scoped的<style>块中（如 Vue 的App.vue、React 的index.css），直接写：:root { --z-toast: 800; --z-dropdown: 900; --z-modal: 1000; } - UniApp 等跨端框架尤其要注意：
uni.showToast渲染的 DOM 在<body>下，如果变量只定义在某个 page 文件里，它完全看不到 - 原生组件（如
uni-modal）class 名不固定，不能靠.uni-modal选择器注入样式，得用属性选择器：[data-type="modal"] { z-index: var(--z-modal) !important; position: relative; }
变量怎么声明才真正可控：作用域、命名和数值设计
--z-modal: 1000写在:root里看似方便，但一旦弹窗组件升级这个值，侧边栏菜单也可能被意外顶起——所有引用它的组件都跟着动。
立即学习“前端免费学习笔记（深入）”；
- 更稳妥的是按功能域就近定义变量。比如模态框组件内部写：
.modal { --z-element: var(--z-modal, 1000); z-index: var(--z-element); }；下拉菜单则用--z-dropdown，Toast 用--z-toast，彼此隔离 - 禁止跨模块复用同名变量，哪怕值相同——
@z-focus-ring在Button和Modal中语义不同，将来必然分家 - 数值要预留间隙：相邻层级至少差 10（如
--z-tooltip: 300，--z-modal: 900），给中间插入新层留余地 - 别用
calc(var(--z-base) + 10)嵌套太深，旧版 Safari 对calc+var()嵌套支持不稳定
父容器悄悄创建了新层叠上下文，变量再准也没用
写了z-index: var(--z-modal)，但弹窗还是被带opacity: 0.99的卡片挡住——问题不在变量，而在卡片自己触发了新堆叠上下文，把整个子树锁死了。
- 触发新层叠上下文的常见属性：
transform（哪怕只是translateZ(0)）、opacity: 0.99、filter、will-change - 调试时看浏览器「Layers」面板，或临时移除可疑父级样式确认是否恢复预期层级
- 若必须保留（如动画优化），就把需要提层的元素“提”到更高层级容器中，而不是硬调子元素的
z-index - 真需要模糊又想保层级？把
filter: blur(1px)移到子元素上，而不是父容器
真正难的不是写对变量，而是时刻意识到：z-index永远不是孤立数字，它活在定位属性和层叠上下文构成的嵌套关系里。变量只是让这个关系更可控，不是绕过它的捷径。
