z-index不生效主因是元素未建立定位上下文，须设position为relative/absolute/fixed/sticky；CSS变量需正确声明与引用，按功能域作用域隔离避免冲突，推荐小步进策略统一管理。
z-index 不生效？先确认元素是否建立了定位上下文
很多情况下 z-index 看似没反应，根本原因不是写错了值，而是目标元素压根没进入“堆叠上下文”——它得是 position 为 relative、absolute、fixed 或 sticky 的才行。静态定位（static）的元素哪怕写了 z-index 也完全被忽略。
- 检查浏览器开发者工具里该元素的 computed 样式，看
position是否已生效 - 父容器如果也设置了
z-index且形成了新的堆叠上下文，子元素的z-index只在该父容器内部起作用，无法越级盖过兄弟容器 - 避免滥用
position: relative+z-index做“伪层叠”，容易意外截断事件或破坏文档流
CSS 变量定义 z-index 值：语法和作用域限制
用 --z-modal 这类自定义属性存数值没问题，但必须配合 z-index: var(--z-modal) 使用；直接写 z-index: --z-modal 是无效的。变量本身不具类型，但 z-index 只接受整数，所以别用 var(--z-base, 10px) 这种带单位的默认值。
- 变量需在 :root 或某个选择器作用域内声明，比如
:root { --z-modal: 1000; } - 变量可被 JS 动态修改：
document.documentElement.style.setProperty('--z-modal', '1200') - 注意 CSSOM 读取时返回的是字符串，JS 中做数值比较前要
parseInt(getComputedStyle(...).getPropertyValue('--z-modal'))
多个组件共用 z-index 变量时，如何避免冲突和覆盖
把所有层级都塞进 :root 容易失控——一个弹窗组件升级了 --z-modal，结果侧边栏菜单也被顶到前面。更稳妥的方式是按功能域划分作用域，让变量就近定义。
- 给模态框组件加 class：
.modal { --z-element: var(--z-modal, 1000); z-index: var(--z-element); } - 下拉菜单、Tooltip、Toast 各自维护自己的
--z-dropdown、--z-tooltip，互不干扰 - 避免在同一个选择器里同时设置变量和使用它，比如
.card { --z-card: 10; z-index: var(--z-card); }—— 这看似简洁，但后续想复用--z-card就得重复声明
z-index 数值过大带来的隐性问题
写个 z-index: 999999 图省事，短期能盖住一切，但长期会埋坑：协作时没人敢动这个值，新组件只能往更高写，最后出现 z-index: 2147483647（32 位有符号整数上限），再加就溢出变负数。
立即学习“前端免费学习笔记（深入）”；
- 推荐用小步进策略，比如基础层
10，弹窗100，全屏遮罩110，顶部提示200 - 用 CSS 变量统一管理步进：
:root { --z-step: 10; --z-modal: calc(var(--z-step) * 10); } - 注意 Safari 对超大
z-index的解析偶尔异常，尤其混用 transform 触发硬件加速时，建议控制在10000以内
真正难的不是怎么设值，是怎么让不同人、不同时间改的代码，在叠加时依然可预期。变量只是工具，分层逻辑和协作约定才是关键。
