应使用 @function 封装 z-index 层级逻辑，定义语义化层级变量与映射表，配合 @use 模块化导入，杜绝硬编码数字和全局污染，确保层级可维护、可理解、可扩展。
用 @function 封装层级计算逻辑，别硬写 z-index 数字
直接写 z-index: 9999 或 z-index: 100 是最常见也最危险的做法。一旦多个组件叠加顺序变化，或引入第三方弹窗库，z-index 冲突几乎必然发生，且调试时很难定位来源。
正确做法是用 @function 抽象层级语义，比如定义基础层、浮层、模态框、全屏覆盖等类别，再通过参数组合生成唯一值：
@function z($layer, $level: 0) {
$layers: (
"base": 0,
"dropdown": 100,
"tooltip": 200,
"modal": 500,
"overlay": 900,
"toast": 1000
);
@return map.get($layers, $layer) + $level;
}
调用时写 z-index: z("modal", 2)，编译后是 z-index: 502；后续调整“modal”基值只需改一处，所有依赖自动同步。
- 函数必须返回单一数值，不能返回选择器或样式块
- 避免在函数里做复杂条件判断（如嵌套多层
@if），会降低可读性和调试效率 - 不要把
z()当作万能加法器——z("modal", z("tooltip", 1))这类递归调用会让层级关系失控
@use 导入函数文件，禁止 @import 污染全局作用域
如果你把 z() 函数放在 _functions.scss 里，旧写法 @import "functions" 会让它直接进入全局，和其他模块的同名函数冲突，CI 构建可能悄无声息地覆盖掉关键逻辑。
必须改用 @use 并显式访问：
@use "functions" as fn;
.modal {
z-index: fn.z("modal");
}
这样即使另一个模块也定义了 z()，也不会互相干扰；而且 IDE 能准确定位到函数定义位置。
- 路径只能是相对路径或
includePaths配置的别名，不能是 URL 或绝对路径 - 文件名必须以下划线开头（如
_functions.scss），否则会被误编译成独立 CSS 文件 - 第三方 Sass 库（如
sass:math）也要用@use "sass:math"，不能@import
层级函数要配合设计系统变量，不裸露数字
光有 z() 函数还不够。如果 $layers 映射表里还写着 "modal": 500，那这个 500 本身仍是魔法数字，没人知道它和“遮罩层”的关系。
应把层级基准值也抽成语义化变量，集中管理：
$z-base: 0;
$z-dropdown: 100;
$z-modal: 500;
$z-overlay: 900;
@function z($layer, $level: 0) {
$layers: (
"base": $z-base,
"dropdown": $z-dropdown,
"modal": $z-modal,
"overlay": $z-overlay
);
@return map.get($layers, $layer) + $level;
}
这样所有层级值只在一个地方维护，且变量名自带含义。设计师说“弹窗要压在遮罩上”，你只需确认 $z-modal ，不用翻代码找数字。
- 禁止在函数体内部硬编码数值，哪怕只是临时调试
- 层级变量应和
$color-、$spacing-等一起放在_tokens.scss中，不分散 - 如果项目用 BEM，层级命名建议带上下文，如
$z-card-dropdown，而非泛泛的$z-dropdown
嵌套中慎用 & 推导层级，优先靠结构隔离
有人试图在嵌套里用 &__overlay 自动提升子元素层级，比如：
.dialog {
z-index: z("modal");
&__overlay {
z-index: z("overlay"); // ❌ 错误：这会让 overlay 层级脱离设计系统约束
}
}
问题在于：这种写法绕过了统一的层级策略，z("overlay") 可能在其他地方被用于全屏加载，而这里只是局部遮罩，语义已偏移。
更稳妥的方式是让结构决定层级范围，再用函数限定上限：
.dialog {
z-index: z("modal");
&__content { z-index: z("modal", 1); } // 允许内容内浮动元素略高
&__close { z-index: z("modal", 2); }
}
- 嵌套层级本身不解决
z-index问题，它只是 CSS 选择器生成器 - 所有
z-index值必须经过函数，杜绝直接写数字 - 超过三层嵌套时，
&容易误写成& &__item导致选择器爆炸，不如拆成独立选择器
z() 函数，而是让团队所有人——包括刚入职的前端、临时支援的外包、甚至改样式的需求方——一眼看懂 z("toast") 比 z("tooltip") 高，且改一个变量就能全局生效。这要求函数名、变量名、调用方式三者语义一致，缺一不可。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
