必须用 sass 命名变量 + @use 显式引入 + 严格递增留间隙，否则“全局管理”只是假象；手写 z-index 易撞车、难维护，而 $z-modal-overlay: 1000 提供编译报错、语义清晰、顺序可控三重保障。
直接结论：必须用 Sass 命名变量 + @use 显式引入 + 严格递增留间隙，否则所谓“全局管理”只是假象，迟早因手写数字或作用域断链导致弹窗被盖、下拉菜单闪退。
为什么$z-modal: 1000比z-index: 999安全
手写数字不是快，是埋雷。常见错误现象包括：两人同时提交z-index: 1000，但因父容器 stacking context 不同，一个生效一个失效；删组件时不敢动它的z-index，怕影响其他模块；grep 全局找“下一个可用值”，漏掉某处z-index: 1001就撞车。
而$z-modal-overlay: 1000带来三重保障：
- 拼错
$z-moda会在 Sass 编译阶段报错，进不了构建流程 - IDE 悬停可跳转定义，新人一眼看懂语义
- 所有值严格递增且留间隙（如
$z-dropdown: 900、$z-modal-overlay: 1000），后续加$z-combo-box: 950不破坏原有顺序
@use路径和命名空间不能省略
变量写了却没生效，90% 是因为作用域断链。典型错误包括：
- 组件文件里写了
z-index: $z-modal，但根本没@use "src/styles/z-index" - 用了
@use "src/styles/z-index" as z，却写成z-index: $z-modal（漏了z.前缀） - 把变量定义在
:root里再用var(--z-modal)，混用 Sass 变量和 CSS 自定义属性，导致维护割裂
正确做法是统一用@use并带命名空间：@use "src/styles/z-index" as z;.modal { z-index: z.$z-modal-overlay; }
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
JS 动态提层时必须同步 CSS 变量
Sass 变量编译后就没了，JS 读不到$z-modal。如果 Modal 需 hover 时上浮，或主题切换时降级层级，就得靠 CSS 自定义属性桥接：
- 在
_variables.scss中定义后，加一句：:root { --z-modal: #{$z-modal-overlay}; } - CSS 中写
z-index: var(--z-modal);，而非直接引用 Sass 变量 - JS 中用
el.style.setProperty('--z-modal', '1050')，确保与样式层一致
别把所有变量塞进:root——更稳妥的是按模块就近定义，比如.dropdown { --z-dropdown: 900; }，避免跨模块意外联动。
堆叠上下文才是真敌人，z-index只是表象
即使$z-modal-overlay值再大，如果父容器加了transform: translateY(0)或opacity: 0.99，子元素的z-index就只在该局部上下文中起作用。调试时先看「Computed」面板里z-index是否显示为灰掉或auto，再往上查父级是否触发新 stacking context。
关键动作只有三个：
- 给需要提层的容器显式设
position: relative（哪怕只是占位） - 避免在导航根容器上用
filter或will-change: transform - 用 Portal 挂载弹窗时，确保挂载点（如
#overlay-root）有position: relative
数值管理再规范，也救不了层叠上下文崩塌——这是最容易被忽略的底层约束。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
