z-index层级混乱本质是语义缺失、作用域断裂与运行时失联；须用Sass变量定义语义锚点（如$z-modal-overlay: 1000）、导出为CSS自定义属性供JS动态接管，并确保Portal挂载点具备定位上下文。
z-index 层级混乱不是数字没写对，而是语义缺失、作用域断裂、运行时失联。靠 SCSS 管理，核心目标不是“算出一个数”，而是守住三道防线：编译期可校验、CSS 输出可读、JS 运行时可接管。
用 Sass 变量定义语义锚点，不生成 z-index 规则
SCSS 的价值在构建期约束，不在运行时干预。所有$z- 变量只做一件事：声明意图，留出余量，拒绝计算。
常见错误现象：z-index: $z-modal 编译后输出原样字符串（未解析），或多人协作时出现 $z-modal + 10 嵌套调用，最终值不可追溯。
实操建议：
- 值必须为整数，严格递增且留间隙：
$z-tooltip: 700、$z-dropdown: 900、$z-modal-overlay: 1000—— 中间空出 99，方便插新层 - 按职责分区，不跨区越界：
$z-background: -10（压底）、$z-toast: 990（浮层）、$z-modal-content: 1010（弹窗内容） - 禁用
$z-max、$z-9999类别名 —— 无语义、易冲突、破坏 IDE 跳转 - 必须
@use "path/to/z-index" as z，调用时写z-index: z.$z-modal-overlay，否则变量不注入
导出为 CSS 自定义属性，供 JS 动态读写
Sass 变量编译完就消失，z-index: 1000 是死的，var(--z-modal) 是活的。Modal hover 展开下拉、Portal 挂载后提层、动画中防闪烁——这些都依赖运行时控制。
常见错误现象：组件里写了 z-index: var(--z-modal)，但 :root 里没定义该变量；或同时混用 $z-modal 和 var(--z-modal)，导致样式和 JS 修改不同步。
立即学习“前端免费学习笔记（深入）”；
实操建议：
- 在变量文件末尾加：
:root { --z-modal: #{$z-modal-overlay}; } - 组件内直接使用：
z-index: var(--z-modal) - JS 动态调整：
element.style.setProperty('--z-modal', '1050')，确保视觉与逻辑一致 - 避免全局塞满
:root；更稳妥的是模块就近导出，如.dropdown { --z-dropdown: #{$z-dropdown}; }
Portal 类组件必须手动接管 stacking context
createPortal 或 teleport 把 Tooltip 挂到 <body> 下，不等于它就“站得高”。<body> 默认不是定位元素，不构成 stacking context，它的子元素会和全站所有 fixed 元素平级比大小。
常见错误现象：Tooltip 挂到 body 后仍被第三方库的 z-index: 2147483647 盖住；多个 Modal 共用一个挂载点，后打开的反而被先打开的遮挡。
实操建议：
- 挂载后检查并设置：
document.body.style.position = 'relative'（若未设） - 多个 Portal 共用挂载点时，JS 必须动态递增自定义属性值，比如每次打开 Modal 就执行
document.documentElement.style.setProperty('--z-modal', String(currentZ + 10)) - 动画开始前提升
--z-modal，防止transform触发新 stacking context 导致闪烁 - 给 Portal 挂载点加 wrapper，并设
position: relative; z-index: 1，把层级控制收束到可控节点
别信 SCSS Map 或函数计算 z-index
$z-index-map: (modal: 1000, tooltip: 950) 看起来结构清晰，实际只是把魔法数字包装了一层。编译后仍是静态字面量，对 opacity: 0.99 创建的新 stacking context 完全无感。
常见错误现象：下拉菜单嵌在 Modal 内，z-index: 950 被 Modal 容器截断，DevTools 里看到值是对的，但就是不可见。
实操建议：
- 禁止写
@function get-z-index($key) { @return map-get($z-index, $key) + 10; }—— 调试时看不到来源，覆盖时无法精准定位 - 放弃“自动推导上下文”的幻想：SCSS 不知道 DOM 结构是否被
transform切割，也不知道 Portal 是否已挂载 - 如果非要保留 Map，仅用于注释和文档：
/* --z-modal: #{map-get($z-anchor, modal)}; */ .modal { z-index: 1000; }，不参与任何逻辑
真正难的不是写对数字，而是意识到：z-index 的战场不在 SCSS 文件里，而在浏览器渲染树中 —— 那里有 stacking context 的嵌套、DOM 挂载时机、CSS 属性副作用，以及 JS 对真实状态的响应能力。
