z-index类名无效首要原因是元素未定位，必须显式设置position: relative/absolute/fixed/sticky；其次需排查祖先元素是否因opacity<1、transform等触发层叠上下文，导致子元素z-index被限制在局部范围内；最后确认tailwind.config.js中zIndex是否正确定义在theme.zIndex对象里且重启了开发服务器。
z-index类名写了但没效果，先查position是否生效
Tailwind 的 z-50、z-100 这类类名只对已定位元素起作用。如果元素仍是 position: static（默认值），浏览器直接忽略 z-index 声明——不是“效果弱”，是压根不读。
- 常见误操作：只加
z-50，漏掉relative或其它定位类 - 在
flex/grid容器里给子项加z-50，误以为布局模式能替代定位 - 用 JS 动态切换 class 时，只更新 z 类，没同步补上
relative
快速验证：打开开发者工具 → 选中元素 → 在「Computed」面板搜 position，若值为 static，那就不用往下看了，先加 relative 再说。
父容器悄悄创建了层叠上下文，子元素z-index被锁死
即使你给子元素写了 absolute 和 z-999，只要它任意一个祖先元素满足以下任一条件，就会创建独立的层叠上下文（stacking context），把子元素的 z-index 关进“小盒子”里：
-
opacity小于 1（比如opacity-99） -
transform非none（哪怕只是translateZ(0)或scale(1)） -
filter、will-change、isolation: isolate、backdrop-filter
此时子元素的 z-999 只能跟同个父容器下的兄弟比高低，盖不过隔壁 z-1 的弹窗——因为它们不在同一个上下文里。
立即学习“前端免费学习笔记（深入）”；
排查技巧：
- 在「Computed」面板里搜
stacking context，标为Yes即中招 - 临时注释掉父级可疑样式（如
opacity-99、transform），看遮挡是否消失 - 必须保留动效？那就别只调子元素，改用
z-[value]提升父容器本身，或把目标元素用 JS 移到document.body下 +fixed手动定位
tailwind.config.js 里 zIndex 配置写错位置或格式
Tailwind v3.0+ 的 zIndex 必须明确定义在 theme.zIndex 对象里，数组写法、放错层级、键名不加引号，都会导致 CSS 规则根本没生成。
- ✅ 正确写法：
module.exports = { theme: { zIndex: { 'background':'0', 'dropdown':'30', 'tooltip':'40', 'modal':'50', 'max':'2147483647' } } } - ❌ 错误写法：写在
extend.zIndex里（不会覆盖默认空值，等于白配） - ❌ 错误写法：用数组：
zIndex: ['0', '10', '50']（v3 已废弃） - ⚠️ 键名必须加引号：
'50': '50'而非50: '50'（JS 会转成数字键，可能导致不可预期行为）
改完配置后必须重启开发服务器——Tailwind 不热重载 tailwind.config.js 变更。
为什么手动写 z-100 / z-9999 不靠谱
硬塞大数字看似能“压住一切”，实则埋下三重隐患：
- 第三方库（如 Headless UI、Radix）自带
z-10、z-50等类，它们的 CSS 注入顺序可能晚于你的 Tailwind 输出，导致覆盖 - 多个组件各自定义
z-50，但语义不同（一个给 Toast，一个给 Dropdown），冲突时无法溯源 - 构建缓存或 Vite/HMR 机制偶尔打乱 CSS 声明顺序，
z-9999可能意外被后加载的样式降级
推荐做法：在 tailwind.config.js 中统一声明职责明确的键名，比如 'modal-overlay': '60'、'modal-content': '70'，然后在 HTML 中写 class="z-modal-overlay"。所有组件必须用这些语义名，禁用原始 z-* 数字类。
真正卡住人的从来不是 z- 值写多少，而是没意识到：每个 position: relative/absolute/fixed 元素是否处在同一层叠上下文里。检查父级有没有无意中触发新上下文，比反复调大 z- 数字管用得多。
