弹窗z-index不生效的根本原因是未满足两个硬条件：元素position必须非static（如relative、absolute），且不能被父级层叠上下文隔离；常见坑点包括未设定位、父元素含transform/opacity等触发新上下文，以及动态拼接z类导致构建漏生成。
弹窗z-index不生效？先看position和层叠上下文
直接加z-modal-overlay没反应，大概率不是数值太小，而是两个硬条件没满足：元素自身position必须是非static（比如relative、absolute），且它不能被父级意外创建的层叠上下文“锁住”。常见踩坑点包括：
- 给
<div>加z-50但没设position: relative→ 完全无效 - 模态框套在
transform: scale(0.99)或opacity: 0.99的容器里 → 子元素z-70只在该局部上下文中起作用 - 两个兄弟弹窗各自父容器都触发了新层叠上下文 → 它们的堆叠顺序由 HTML 顺序决定，跟 z 值无关
为什么z-999 / z-[999]不是解法
硬塞大数字或动态拼接z-[${depth}]看似能压住一切，实则埋雷：
-
z-[999]依赖 JIT 扫描字面量字符串，React 中class={`z-[${depth}]`}构建时根本不会识别，生产环境必漏生成 - 第三方库（如 Headless UI）注入的 CSS 可能晚于 Tailwind 输出，
z-10反而盖过你的z-999 - 没人知道
z-[999]对应什么 UI 角色，下次加个 Tooltip，该用 998 还是 1001？冲突后无法溯源
必须用theme.zIndex集中定义语义化层级
放弃零散数字，在tailwind.config.js中统一声明带职责的键名。关键点：
- 必须写在
theme.zIndex下，不是extend.zIndex；键名必须是字符串（'modal-overlay'✅，modal-overlay❌） - 数值之间留间隙（比如
dropdown: '30'和tooltip: '40'），方便未来插中间层 - 改完必须重启开发服务器——Tailwind 不热重载配置变更
- 组件内统一用
z-modal-overlay，禁用z-60或z-[60]
第三方组件覆盖怎么办
Headless UI 的 Menu.Items 默认用z-10，但你的z-dropdown是 30，它仍可能被压——因为样式注入顺序或!important干扰：
立即学习“前端免费学习笔记（深入）”；
- 优先查文档：Radix 的 Portal 支持传
className，直接塞z-dropdown - 若不支持，在
@layer components中重写其选择器：.headless-menu-items { @apply z-dropdown; } - 切忌全局加
!z-dropdown——!会破坏可维护性，且掩盖真实层叠逻辑
最常被忽略的是：z-index 生效的前提不是“数字够大”，而是定位状态干净、层叠上下文未被污染、语义命名已落地到配置和组件中。一旦漏掉其中一环，再大的数字也白搭。
