Tailwind的z-*类默认不按数值顺序生效，因其离散值易被第三方插件或自定义配置打破全局单调性，导致层级混乱；应通过theme.zIndex集中配置语义化层级（如z-background、z-modal-content），统一管理并避免冲突。
为什么Tailwind的z-*类默认不按数值顺序生效
Tailwind 默认的 z-index 工具类（如 z-0、z-10、z-50）在 CSS 中生成的是离散值，但它们**不保证全局单调递增**——比如 z-50 可能被定义为 z-index: 50，而第三方插件或自定义配置里加了个 z-drawer 对应 z-index: 9999，这时层级就跳出了原有序列。更常见的是：不同组件库、Modal、Toast、Tooltip 各自维护一套 z- 命名，互相覆盖时完全不可预测。
如何用theme.zIndex建立可扩展的统一索引表
核心是放弃零散声明，改用 Tailwind 的 theme.zIndex 配置集中管理所有层级语义值。这不是“加更多数字”，而是按 UI 职责分层：
-
z-0→ 底层容器（background） -
z-10→ 内容区域（content） -
z-20→ 固定头部/底部（sticky） -
z-30→ 下拉菜单、Popover（dropdown） -
z-40→ Tooltip（tooltip） -
z-50→ Toast / Snackbar（toast） -
z-60→ Modal 背景遮罩（modal-overlay） -
z-70→ Modal 主体（modal-content） -
z-80→ 全局加载层（loading-overlay） -
z-90→ 全屏编辑器浮层等（editor-overlay）
在 tailwind.config.js 中这样写：
module.exports = {
theme: {
extend: {
zIndex: {
'background': '0',
'content': '10',
'sticky': '20',
'dropdown': '30',
'tooltip': '40',
'toast': '50',
'modal-overlay': '60',
'modal-content': '70',
'loading-overlay': '80',
'editor-overlay': '90',
}
}
}
}
之后直接用 z-background、z-modal-content，语义清晰，且天然避免冲突。
立即学习“前端免费学习笔记（深入）”；
遇到第三方组件（如 Headless UI、Radix）覆盖怎么办
这些库常自带内联 z-index 或硬编码样式，比如 Headless UI 的 Menu.Items 默认 z-10，但你的 z-dropdown 是 30，它仍可能被压住——因为它的样式在 Tailwind 之后注入，或用了 !important。
- 优先查该组件文档是否支持
class覆盖（如 Radix 的portal组件允许传className） - 若不行，在
@layer components中重写其选择器，并显式指定z-dropdown等语义类 - 极端情况需用
!z-dropdown（Tailwind 3.3+ 支持），但这是妥协，不是设计 - 永远不要在项目里再出现
z-[999]或z-[10000]—— 这等于主动放弃标准
为什么不用纯数字而要语义化命名
数字本身没有上下文。当某天产品提需求：“Toast 要盖过 Modal”，你改 z-toast 从 50 到 75，整个系统立刻崩：所有依赖原顺序的交互（比如 Modal 里的下拉菜单）都会错位。而语义化命名强制你思考层级意图：z-toast 和 z-modal-content 是并列还是包含？要不要新增一个 z-global-toast？这种讨论会暴露设计盲区。
真正难的不是写对数字，而是让团队所有人对“浮层谁该在谁上面”有一致认知。配置表只是载体，共识才是关键。
