必须用 Sass 变量 + CSS 自定义属性双轨管理 z-index，否则项目越往后越容易出现弹窗被遮、侧边栏错位、Tooltip 消失等线上事故；因其通过命名变量实现语义化、编译期校验、留隙递增与职责分区，并导出为 CSS 变量以支持 JS 动态读写和主题切换，同时规避 stacking context 隐式创建导致的层级失效。
必须用 Sass 变量 + CSS 自定义属性双轨管理 z-index，否则项目越往后越容易出现弹窗被遮、侧边栏错位、Tooltip 消失等线上事故。
为什么不能直接写 z-index: 9999
这不是“写得不够规范”的问题，而是语义断裂+维护雪崩的起点：
- 别人看不懂
9999是 modal 遮罩还是全屏编辑器，改一个值可能连带影响七八个组件 - 两个模块各自写了
z-index: 1000，但父容器 stacking context 不同，结果一个在上一个在下，排查要翻三小时 DOM 树 - 删掉一个旧弹窗组件后，不敢动它的
z-index，怕影响 toast 或 dropdown；加新组件时得全局搜索所有z-index值再手动找“空档”
用 Sass 变量定义层级锚点，不是为了炫技
核心是把“谁该在谁上面”显式声明为可读、可查、可跳转的命名变量，而不是靠数字大小猜意图：
- 所有值严格递增且留间隙（如
$zindex-dropdown: 100、$zindex-sidebar: 200、$zindex-modal-shade: 1000），方便后续插入中间层级（比如新增 tooltip 可设为150） - 禁止用数组顺序隐式映射（如
$zlist: (dropdown, sidebar)→ 自动赋值 1/2），一旦删中间项，下游所有值全变，不可控 - 变量名必须带业务语义（
$zindex-toast而非$zindex-3），IDE 点击可跳转，搜索可定位，拼错会编译报错
CSS 自定义属性同步导出，支撑运行时动态调整
Sass 编译期变量无法被 JS 读取或响应式覆盖，必须通过 :root 同步为 CSS 变量：
立即学习“前端免费学习笔记（深入）”；
:root {
--z-dropdown: #{$zindex-dropdown};
--z-sidebar: #{$zindex-sidebar};
--z-modal-shade: #{$zindex-modal-shade};
}
- JS 动态插入浮层时可直接读
getComputedStyle(document.documentElement).getPropertyValue('--z-modal-shade') - 主题切换时可通过 JS 批量重设
document.documentElement.style.setProperty('--z-modal-shade', '1050') - 避免工具类硬编码（如
.z-100），否则断点响应式时无法统一升维（md:z-100和lg:z-100数值冲突）
真正致命的坑不在 z-index 数字本身
绝大多数“z-index 失效”问题，和你写的数字完全无关：
- 目标元素没设
position: relative/absolute/fixed——z-index直接被浏览器忽略，Computed 面板里显示auto - 最近定位祖先（如
.menu-item）没设position: relative，子菜单会飞到下定位，脱离预期上下文 - 父容器设置了
opacity: 0.99、transform: translateY(0)、filter: blur(0)等任意一项，就创建了新 stacking context，子元素再大的z-index也出不来
调试时优先打开 DevTools 的 Computed 面板，看目标元素的 z-index 是否生效、它的 stacking context 祖先是谁——这才是比“该不该用 9999”重要十倍的事。
