Sass变量比CSS自定义属性更适合z-index常量，因其编译期报错、支持嵌套与主题化、可类型推导；需按职责分区留间隙、禁用魔法数字，并同步JS常量以保障层级一致。
z-index 层级混乱不是数值没写对，而是缺乏语义化约束和结构共识；用 Sass 变量建立映射表是最小侵入、编译期可校验的解法。
为什么 Sass 变量比 CSS 自定义属性更适合层级常量
Sass 编译时就能报错，比如拼错 $z-moda 会直接中断构建，而 var(--z-moda) 在运行时才失效，更难定位；Sass 还支持嵌套作用域和条件导出，适合组件库拆分；CSS 自定义属性虽可在 JS 中读取，但无法做类型约束——Z_INDEX.modal 能被 TypeScript 精确推导，var(--z-modal) 只是字符串。
- 变量名错误在
sass build阶段即暴露，不进生产环境 - 支持
@use "z-index" with ($base: 1000);实现主题化偏移 - 避免
:root全局污染，可按模块隔离（如_z-modal.scss仅导出 modal 相关） - 第三方组件覆盖时，可用
@include z-index-overwrite(dropdown, 950);局部修正
如何设计不撞车的 Sass z-index 映射表
关键不是数字大小，而是留足间隙、按职责分区、禁止跨区越界。例如 $z-dropdown: 900; 和 $z-modal: 1000; 之间留 99 的空档，后续加 $z-combo-box: 950; 不影响原有顺序；所有值必须为整数，禁用浮点或计算表达式（如 1000px 或 $z-modal + 1），防止编译后不可控。
- 基础层：
$z-background: -10;（压底图）、$z-default: 1;（普通内容） - 浮层层：
$z-tooltip: 700;、$z-dropdown: 900;、$z-toast: 990; - 强弹窗层：
$z-modal-overlay: 1000;、$z-modal-content: 1010; - 禁止使用
$z-9999或$z-max类别名——它违背语义，且与 Headless UI 等库默认值冲突
常见错误：Sass 变量写了却没生效
最典型的是忘了 @use 或 @import，导致变量未注入作用域；其次是组件中写 z-index: $z-modal; 但该文件没引入变量文件；还有人把变量写在 :root 里再用 var() 混用，破坏了 Sass 的类型安全。
立即学习“前端免费学习笔记（深入）”；
- 确认
@use "path/to/z-index" as z;后，调用z.$z-modal（带命名空间）或@use "path/to/z-index" with (...); - 禁止在同一个文件里既用
$z-modal又用var(--z-modal)，会造成维护断层 - 检查编译后 CSS 是否真输出了对应值——若输出
z-index: $z-modal;说明变量未解析，大概率是路径错误或未@use - VS Code 中装 Sass IntelliSense 插件，悬停能看变量定义位置，快速定位未引入问题
和 JS 运行时层级同步的必要动作
Sass 变量无法被 JS 读取，所以 Modal 组件动态栈、Tooltip 的 show/hide 控制等逻辑，必须手动维护一份 JS 常量。否则会出现「CSS 显示 modal 是 1000，JS 动态插入的 loading 层设了 1001，但实际被压在下面」——因为 JS 层没同步 Sass 的语义体系。
- 新建
z-index.ts，内容与 Sass 变量严格一一对应：export const Z_INDEX = { modal: 1000, modalOverlay: 1000 } as const; - 用脚本自动比对 Sass 文件和 TS 文件的键值是否一致（CI 阶段跑），避免人工不同步
- React/Vue 组件中，只允许通过
Z_INDEX.modal设置内联style.zIndex，禁用硬编码数字 - 注意：Sass 中
$z-modal-overlay和 JS 中Z_INDEX.modalOverlay命名风格需统一，建议都用 kebab-case 或 camelCase，避免混淆
真正难的不是定义变量，而是让所有人遵守同一套命名和分区规则；一旦有人绕过变量直接写 z-index: 1234，整个体系就崩了一角。工程上最有效的约束，是 CI 检查 + PR 模板强制填写「z-index 使用依据」字段。
