必须用 sass 变量 + mixin 统一管理 z-index，因其可避免手写数字导致的语义缺失、层级冲突与维护困难；需定义严格递增且留间隙的命名变量（如 $zindex-modal-shade: 1000），并配合校验型 mixin 确保安全调用。
直接结论：用 Sass 变量 + mixin 统一管理 z-index 值，不是“可选优化”，而是避免线上弹窗被遮盖、侧栏浮层错位等事故的底线做法。
为什么不能手写 z-index 数字
手写 z-index: 999 或 z-index: 9999 看似快，实际埋下三类问题：
- 数值无语义：别人看不懂
1200是弹窗遮罩还是 toast 提示 - 易冲突：A 模块写
z-index: 1000，B 模块也写1000，但父容器 stacking context 不同，结果 B 被压在下面 - 难维护：删一个组件时，不敢动它的
z-index，怕影响其他地方；加新组件时，得翻遍全项目找“下一个可用值”
如何用 Sass 定义可读、可扩展的 z-index 映射表
核心是把层级关系显式声明为有序列表，而非零散变量。参考你知识库中已有的 $zindexlist 结构，但需补足两点关键改进：
- 用命名变量代替裸字符串（如
$zindex-modal-shade: 1000），避免拼写错误和 IDE 无法跳转 - 所有值必须严格递增且留有间隙（如
100,200,1000,2000），方便后续插入中间层级（比如新增tooltip可插在200和1000之间） - 不推荐用数组顺序隐式决定数值（如
$zindexlist: sidebar modal→ 自动映射为1/2），因为一旦增删中间项，下游所有值全变，风险不可控
推荐写法示例：
$zindex-base: 1; $zindex-dropdown: 100; $zindex-sidebar: 200; $zindex-modal-shade: 1000; $zindex-modal: 1010; $zindex-toast: 2000; $zindex-overlay: 3000;
@include zindex($name) mixin 的安全用法
你知识库中提到的 @include zindex($ele) 是个好思路，但要注意它依赖全局 $zindexlist 数组，存在隐式耦合。更可控的做法是直接引用命名变量：
- 不要写
@include zindex(modal)这种需查表的调用，改用z-index: $zindex-modal; - 如果坚持用 mixin，确保它只做一件事：校验传入名是否在白名单内，并强制转换为数字（避免传错字符串导致编译不报错但 CSS 失效）
- 切勿在 mixin 内部动态计算值（如 “比
modal高 10”），这会让依赖关系不可追溯
简单 mixin 示例（带基础防护）：
@mixin zindex($name) {
@if $name == modal-shade {
z-index: $zindex-modal-shade;
} @else if $name == modal {
z-index: $zindex-modal;
} @else {
@error "Unknown z-index name: #{$name}. Valid options: modal-shade, modal";
}
}
最容易被忽略的 stacking context 陷阱
再规范的 z-index 值，遇上错误的 stacking context 也会失效。常见翻车点：
- 父容器设置了
position: relative但没设z-index（或设为auto），子元素的z-index: 9999依然会被兄弟容器里z-index: 1的元素盖住 opacity 、<code>transform、filter等属性会隐式创建新的 stacking context，导致内部z-index仅在该局部生效- IE6/7 中未声明
z-index的定位元素默认为0，而现代浏览器是auto，跨浏览器调试时容易误判
验证方法：Chrome DevTools 的 Layers 面板能直观显示 stacking context 树，比猜更可靠。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
