z-index: var(--z-modal) 无效的首要原因是未设置 position（必须为 relative/absolute/fixed/sticky）；其次检查 CSS 变量是否为纯数字、作用域是否可达、祖先是否创建了层叠上下文。
z-index: var(--z-modal) 无效，90% 是因为没设 position
写了 z-index: var(--z-modal) 却盖不住兄弟元素，第一反应不该是改变量值，而是打开开发者工具看「Computed」面板：如果 z-index 显示为 auto 或灰掉，说明它根本没被激活。原因只有一个——目标元素的 position 还是 static（默认值）。z-index 对 static 元素完全无效。
必须显式设置为以下之一：relative、absolute、fixed 或 sticky。哪怕只是想用变量控制层级，也得先“激活”定位能力。
CSS 变量不能参与字符串拼接或算术运算（除非用 calc()）
z-index 只接受整数或 auto，不接受字符串。而 CSS 变量（如 --z-modal: "1000"）若带引号或写成非数字格式，浏览器会当字符串处理，导致解析失败——此时 z-index 回退为 auto，等效于没写。
- ❌ 错误写法：
--z-modal: "1000"; z-index: var(--z-modal); - ✅ 正确写法：
--z-modal: 1000; z-index: var(--z-modal); - ⚠️ 若需动态计算（比如叠加偏移），必须走
calc()：z-index: calc(var(--z-modal) + 10);
变量作用域失效：scoped 样式或 Shadow DOM 里取不到 --z-modal
在 Vue 的 、Web Components 的 Shadow DOM，或某些 CSS-in-JS 方案中，:root 定义的 --z-modal 默认不可见。浏览器会静默忽略 var(--z-modal)，z-index 回退为 auto。
解决方式取决于上下文：
- Vue SFC：把变量定义在全局
块，或用:deep()/::v-deep注入 - Shadow DOM：需在组件内部的
:host或中重新定义变量，或通过inherit显式继承 - 构建工具（如 PostCSS）：确认未启用 CSS 变量提取/重命名插件，否则变量名可能被混淆
父容器意外创建层叠上下文，锁死子元素 z-index 范围
即使 z-index: var(--z-modal) 解析成功、元素也设了 position: absolute，仍可能被盖住——因为它的某个祖先触发了新的层叠上下文（stacking context），比如：
-
opacity: 0.99（小于 1） -
transform: translateY(0)（非none） -
filter: blur(0)（非none） will-change: transform
一旦发生，子元素的 z-index 就只在这个局部上下文中比较，再大也出不去。这时检查祖先链比调大变量值更有效。
真正麻烦的不是变量写不对，而是你以为变量生效了，其实它早就被 position: static 或 opacity: 0.99 静默拦截了——这两处最容易漏看。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
