Tailwind 的 z-index 类名按固定步长递增而非连续整数，导致嵌套组件易层级错乱；需通过配置 theme.extend.zIndex 自定义缺失值，并优先使用语义化命名，同时理解 z-auto 与 stacking context 的作用机制。
Tailwind 默认的 z-index 类名（如 z-0、z-10、z-20）不是连续整数，而是按固定步长递增的离散值——这在多数布局中够用，但一旦涉及模态框嵌套、下拉菜单叠加或第三方组件（如地图图层、富文本编辑器浮层），就容易出现层级错乱。
为什么 z-50 不等于 CSS 的 z-index: 50
Tailwind 的 z- 类名映射到的是预设数值，不是原始数字。默认配置里：z-0 → 0，z-10 → 10，z-20 → 20，z-30 → 30，z-40 → 40，z-50 → 50。看起来是直译，但问题出在「中间缺值」：没有 z-1、z-15 或 z-45，而某些 UI 库（比如 Headless UI 的 Popover）内部用的是 z-50，你自己的 Tooltip 若只用 z-40，就会被盖住。
- 检查你用的 Tailwind 版本：v3.0+ 默认提供
z-0到z-50，步长为 10；v4 开始改用更细粒度的z-10～z-60（仍非全整数） - 不要假设
z-50是“最高”——它只是默认配置里的最大值，可被自定义覆盖 - 第三方组件文档里写的 “requires z-50” 往往是保守值，实际可能只需
z-45就能压住它，但 Tailwind 没这个类
如何添加缺失的 z-1、z-7 等精细值
直接扩展现有 z-index 配置比写 inline style 更可靠，也避免污染 HTML 结构。在 tailwind.config.js 的 theme.extend.zIndex 中注入自定义键值对即可：
module.exports = {
theme: {
extend: {
zIndex: {
'-1': '-1',
'1': '1',
'7': '7',
'45': '45',
'tooltip': '999',
'modal': '1000',
}
}
}
}
这样就能在模板中使用 z--1（注意双短横）、z-1、z-7、z-45、z-tooltip 等类名。注意：
立即学习“前端免费学习笔记（深入）”；
-
z--1是合法类名，Tailwind 能正确解析为z-index: -1，但需确保你的构建工具（如 PostCSS）未过滤掉含双短横的类 - 命名建议带语义（如
z-tooltip），而不是堆砌数字，方便团队理解用途 - 如果项目已用
@layer utilities手动加过z-1，要删掉，否则和 config 冲突
何时该用 z-auto 而不是硬编码数值
z-auto 对应 z-index: auto，它不是“无层级”，而是交由浏览器根据 DOM 顺序和定位上下文自动计算。常见适用场景：
- 纯静态布局中，多个
position: relative元素仅靠源码顺序控制叠放（无需 z-index） - 子组件继承父容器的 stacking context，且不希望它脱离该上下文（例如卡片内的图标悬浮态）
- SSR 渲染时避免因服务端/客户端 z-index 计算差异导致闪烁
反例：给一个 fixed 的 Header 加 z-auto，它会退回到文档流默认层级（通常低于其他 fixed 元素），结果被遮挡——这时必须显式设值，比如 z-50 或更高。
调试层级冲突的三步法
遇到元素被意外遮盖，别急着调大 z- 值：
- 先打开浏览器开发者工具，选中被盖住的元素，看 computed 样式里
z-index是否生效——若显示auto或initial，说明它没建立 stacking context（缺position或transform等触发属性） - 检查父级是否有
z-index且值较低（比如父容器是z-10，子元素设z-50也无效，因为被父级 stacking context 截断） - 用
outline: 1px solid red临时标记疑似干扰元素，快速定位是哪个 DOM 节点在“抢层”
真正难处理的不是数值本身，而是 stacking context 的嵌套关系——z-index 只在同一个 stacking context 内有效，跨 context 时，父级的 z-index 才是决定性因素。
