less 3.5+ 中 @z-index-map 必须为字符串 key 加数字 value，推荐按语义分组、留间隙、小写中划线命名，并用 .each() 自动生成变量与工具类，同时注意层叠上下文限制。
Less 3.5+ 的 @z-index-map 必须是字符串 key + 数字 value
直接写 @z-index-map: { modal: 1000 } 会编译失败——Less 要求 Map 的 key 必须加引号："modal"，否则解析器报错 ParseError: expected '}'。value 也必须是纯数字，1000px、calc(999 + 1) 或字符串 "1000" 全都不行，会中断 .each() 遍历或生成无效 CSS。
推荐结构示例：
@z-index-map: {
"overlay": 9999,
"modal": 9998,
"popover": 9997,
"tooltip": 9996,
"dropdown": 9995,
"sticky-header": 100
};
- 数值留空隙（如 9999→9998），方便后续插入
"toast"或"loading" - 语义分组清晰：弹层类高位、固定元素低位，避免跨域混用
- 所有 key 小写 + 中划线，保证生成的类名
.z-overlay符合 BEM 习惯
用 .each() 同时生成变量和工具类，别手写重复逻辑
Less 自带的 .each() 混合宏能遍历 Map 并产出两样东西：可被其他 Less 文件引用的变量（如 @overlay-z），以及开箱即用的 CSS 类（如 .z-overlay）。不手动写 10 行 @modal-z: 9998，也不用拼接字符串生成类名。
标准写法：
.each(@z-index-map, {
@key: @key;
@value: @value;
@var-name: ~"@{key}-z";
@{var-name}: @value;
.z-@{key} { z-index: @value; }
});
- 生成变量名自动带
-z后缀，比如@tooltip-z，防止命名冲突 - 类名统一前缀
.z-，调试时直接在 HTML 上加class="z-modal"快速验证 - 若 Map 里有
"sticky-header"，生成的是.z-sticky-header，不是.z-sticky_header（下划线会被忽略）
Map 生成的 z-index 只在当前层叠上下文内有效
写了 .z-modal { z-index: 9998 } 却盖不住隔壁 .sidebar？大概率不是变量没生效，而是两个元素不在同一层叠上下文里。比如 .sidebar 的父容器设置了 transform: translateY(0)，它就创建了新层叠上下文，子元素再高的 z-index 也只能在那个“小盒子”里比大小。
- 检查开发者工具「Computed」面板：如果
z-index显示为auto，说明元素没定位（缺position） - 往上逐级看父元素是否带
opacity 、<code>filter、will-change或非none的transform - Portal 类弹窗挂到
时，务必给body加position: relative，否则挂载点无层叠上下文基准
别把 @z-index-map 当全局开关，层级语义要绑定组件作用域
把所有 z-index 都塞进一个 Map 然后全项目 @import，看似统一，实则埋雷。Modal 组件升级 @z-modal 值，会导致 Toast、Dropdown 全部被动上浮——它们根本不需要参与这次调整。
- 按功能域拆分 Map：
@z-modal-map、@z-dropdown-map，各自.each()生成局部变量 - 组件内部用
--z-element: var(--z-modal, 1000)定义 CSS 变量，隔离外部影响 - 第三方库（如 Ant Design）的
@zindex-modal基准值必须查文档确认，然后用@z-modal: @z-antd-modal + 10对齐，而非硬写1010
真正难的不是语法怎么写，是让每个 PR 都检查新增的 z-index 是否有对应语义变量、是否留了间隙、是否绕过了父级层叠上下文限制。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
