APlayer 与浮层的 z-index 之战：移动端遮挡复盘

一个看着很小、其实很典型的前端 bug：移动端上，固定在底部的音乐播放器（APlayer）有时会盖住右下角的 AI 对话浮窗，点不到。这篇复盘根因和处理方式，以及它背后「z-index 治理」这个更大的话题。

现象与定位

桌面端正常，移动端偶发遮挡。打开 DevTools 一看就明白了：APlayer 的固定模式给自己写死了 z-index: 99，而我全站的浮层（站点头部、对话框、抽屉、AI 助手）统一用 z-50（即 z-index: 50）。99 > 50，播放器自然压在 AI 浮窗上面。

桌面端不明显，只是因为两者位置错开、很少重叠；移动端屏幕窄，它俩挤在一起，问题就暴露了。

修复

第三方库的样式是它在 onMounted 时动态注入的，可能晚于我自己的组件样式，所以普通覆盖未必赢。我用 !important 把播放器的层级下调到「内容之上、浮层之下」：

<style>
/*
 * APlayer fixed 模式默认 z-index:99，会盖住本站统一用 z-50 的浮层
 * （站点头部、对话框、抽屉、AI 助手），移动端尤为明显。
 * 将持久型迷你播放器下调到「内容之上、浮层之下」，使模态类 UI 始终在其上。
 * 用 !important 是因为 APlayer 的 CSS 在 onMounted 时动态注入、可能晚于本组件样式。
 */
.aplayer.aplayer-fixed,
.aplayer.aplayer-fixed .aplayer-body {
  z-index: 30 !important;
}
.aplayer.aplayer-fixed .aplayer-list {
  z-index: 30 !important;
}
.aplayer.aplayer-fixed .aplayer-lrc {
  z-index: 29 !important;
}
</style>

层级关系理顺成：普通内容 < 播放器(30) < 各类浮层(50)。播放器依然浮在文章之上方便操作，但模态类 UI 永远压得住它。

这不是「调个数字」，是层级治理

!important + 魔法数字能救急，但如果整站的 z-index 都是「哪里冲突改哪里、随手 +1」，迟早变成 z-index: 9999 的军备竞赛。更可持续的做法是给层级定一套语义化的刻度，集中管理：

:root {
  --z-content: 0;     /* 普通内容流 */
  --z-sticky: 30;     /* 吸顶/迷你播放器等持久控件 */
  --z-overlay: 50;    /* 抽屉、下拉、浮窗 */
  --z-modal: 60;      /* 模态对话框 */
  --z-toast: 70;      /* 全局提示 */
}

原则很简单：

• 同层用同一刻度，不要每个组件自定义；
• 持久控件低于临时浮层：常驻的（播放器、吸顶栏）应该让位给临时弹出的（对话框、菜单），因为后者代表「用户当前正在交互的焦点」；
• 第三方库的层级要主动收编：它们常常给自己设很高的值，引入时就该用一条覆盖样式把它拉回你的刻度体系，而不是等冲突了再救火。

经验

1. 移动端要专门测重叠：很多层级 bug 只在窄屏、元素挤到一起时才现形。
2. 覆盖第三方动态注入的样式，!important 往往是必要之恶，但要写清注释说明「为什么」，否则后人不敢动。
3. 「持久控件让位于临时浮层」是个好默认：符合用户直觉——我点开的东西，就该在最上面。

小结

一次小遮挡，根因是第三方库的高 z-index 与全站浮层刻度冲突。救急靠 !important 把播放器降到「内容之上、浮层之下」；治本靠给整站 z-index 定一套语义刻度并把第三方库收编进来。层级不是随手写的数字，是需要治理的设计。