z-index无效的三大主因：一是元素position为static不参与层叠；二是父级创建了层叠上下文限制子元素z值范围；三是Tailwind配置错误或动态class未被识别。
z-index写了但完全没反应，先查position是不是static
浏览器压根不读你的z-index值，只要元素的position是static（默认值），它就自动被排除在层叠计算之外。这不是“效果弱”，而是“不参与”。
- 只写
z-50，忘了加relative、absolute等定位声明 - 用JS动态添加class时，只加
z-50，漏掉同步设置position: relative - 误以为
flex或grid子项能靠父容器“继承”层级——其实子项自己必须显式声明position
快速验证：打开Chrome DevTools，选中目标元素，在「Computed」面板里搜position，确认最终值不是static；临时加一行position: relative，看z-类是否立刻生效。
父级悄悄创建了层叠上下文，子元素z值被锁死
即使position设对了，z-index也可能被限制在局部范围——只要某个祖先元素满足以下任一条件，它就创建了新的层叠上下文，子元素的z-值只能在它内部比大小：
-
opacity小于1（哪怕opacity: 0.999） -
transform不为none（包括translateZ(0)、scale(1)） -
filter不为none（哪怕blur(0)） -
will-change: transform或will-change: opacity isolation: isolate-
position: fixed或sticky且z-index非auto
调试建议：在DevTools Elements面板中逐级点击父节点，右侧面板「Layout」标签页留意「Stacking context」是否突然变成Yes；临时注释掉可疑父级的transform或opacity，看遮挡是否立刻消失。
立即学习“前端免费学习笔记（深入）”；
tailwind.config.js里zIndex配置错一个字符，CSS规则根本不会生成
Tailwind v3.0+ 已废弃数组写法，也拒绝extend.zIndex追加式配置。所有z-类必须完整定义在theme.zIndex下，且键名必须加引号、值必须是字符串。
- ❌ 错误：
extend: { zIndex: { 'modal-overlay': '60' } }（theme.zIndex默认为空，追加无效） - ❌ 错误：
zIndex: ['0', '10']（数组写法已废弃） - ❌ 错误：
zIndex: { modal-overlay: '60' }（JS解析为modal键，-overlay被截断） - ✅ 正确：
zIndex: { 'modal-overlay': '60', 'tooltip': '40' }
改完配置后必须重启开发服务器——Tailwind不热重载配置变更。
别用z-[999]或动态拼接class
z-[999]看似灵活，实际是维护黑洞，且生产环境极易漏生成。
- 依赖JIT模式扫描
content字段里的字面量字符串 - React中写
class={`z-[${depth}]`}，构建时根本不会识别 - 无法静态分析，PurgeCSS可能误删，CI/CD环境行为不稳定
推荐做法：在theme.zIndex中明确定义常用层级（如'tooltip': '50'、'modal-backdrop': '49'），然后在HTML中写class="z-tooltip"。
真正卡住人的从来不是 z- 值写多少，而是没意识到：每个position: relative/absolute/fixed元素是否处在同一层叠上下文里。检查父级有没有无意中触发新上下文，比反复调大z-数字管用得多。
