z-index不生效的根本原因是元素未参与堆叠上下文；只有position为relative、absolute、fixed或sticky的元素才支持z-index，且其效果受父级堆叠上下文限制。
z-index 不生效？先确认元素是否“参与堆叠上下文”
很多情况下写上 z-index 没反应，不是语法错，而是该元素压根没进入“可被 z-index 控制”的状态。只有定位元素（position 值为 relative、absolute、fixed 或 sticky）才支持 z-index。
- 普通
div默认position: static，设了z-index也完全忽略 -
position: relative是最常用且安全的选择——不改变文档流，又能启用z-index - 父容器若创建了新的堆叠上下文（比如设置了
opacity: 0.99、transform: scale(1)、will-change: transform），子元素的z-index只在该父容器内比较，不会和外部元素直接比大小
z-index 数值怎么设才可靠？别只看数字大小
z-index 的实际效果取决于它所处的堆叠上下文层级，不是全局“越大越上”。两个不同堆叠上下文里的元素，即使子元素 z-index: 9999，也可能被父级更低但上下文更“高”的容器整体压住。
- 避免用魔法数字如
z-index: 999或z-index: 99999，容易失控。建议按语义分层：比如z-index: 10（弹窗遮罩）、z-index: 20（弹窗内容）、z-index: 100（全屏提示） -
z-index支持负值，但负值会让元素沉到其父容器背景之下（如果父容器有背景色或边框，就会看不见） - 不要依赖浏览器默认堆叠顺序去“猜”谁在上，显式设置
position+z-index才可控
常见 z-index 相关错误现象与排查路径
遇到遮挡异常，别急着调数字，先顺着这几条路查：
- 目标元素是否漏写了
position？检查 computed styles 里position是否真的不是static - 它的某个祖先元素是否意外触发了新堆叠上下文？重点看
opacity、transform、filter、will-change、isolation: isolate - 是否用了
z-index: auto（默认值）？它等价于不参与堆叠排序，同级中按 HTML 顺序渲染 - Flex 或 Grid 容器中的子项，即使设了
position: relative，z-index仍有效；但若父容器本身是堆叠上下文，子项依然受限
现代布局中 z-index 的替代思路
纯靠 z-index 维护层级容易变成“数字竞赛”，尤其在组件化、动态插入内容的场景下。有些情况其实可以绕开：
立即学习“前端免费学习笔记（深入）”；
- 用 DOM 插入顺序控制显示优先级：把需要置顶的元素 append 到
body最后（比如 Toast、Tooltip），天然在大多数内容之上 - CSS
isolation: isolate可主动创建堆叠上下文，比靠副作用（如opacity）更明确 - 某些动画/过渡场景，用
transform: translateZ(0)强制提升图层，比z-index更轻量（但它不解决逻辑层级，只影响合成层）
真正难的不是写 z-index，而是判断它在哪一级上下文里起作用。浏览器 DevTools 的 Layers 面板能直观看到堆叠上下文树，比猜强得多。
