解决Tailwind CSS z-index层级乱序：统一层级索引标准

当 Tailwind 的 z-index 层级不再听话

先给一个直接的判断：Tailwind 默认的 z-* 类，虽然叫 z-10、z-50，但这些数字本质上只是一组离散的“标签”，而不是一个全局递增的序列。在实际项目中，第三方插件、自定义组件很容易引入一个 z-9999 或者直接写个内联 z-index: 9999，瞬间就把你精心规划的层级打乱。更常见的情况是不同团队各自维护 Modal、Toast、Tooltip 的 z- 命名，等到它们出现在同一个页面时，互相覆盖、谁压谁完全不可预测。

为什么 Tailwind 的 z-* 类默认不按数值顺序生效

通常来说，Tailwind 默认生成的 z-10、z-50 看起来是按数字排列的，但实际的渲染顺序并不保证全局递增。例如 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？这种讨论会暴露设计盲区。

真正困难的不在于写对数字，而是让团队所有人都对“浮层谁该在谁上面”有一致的认知。配置表只是载体，共识才是关键。