z-index不生效主因是元素未进入层叠上下文：需设置非static定位，且父元素未触发新层叠上下文（如transform、opacity<1等）；变量应按功能域就近定义并预留数值间隙。
z-index不生效？先看元素有没有进入层叠上下文
写了z-index: var(--z-modal)却盖不住隔壁组件，大概率不是变量没生效，而是目标元素压根没资格参与层叠——它没设置position，或父容器悄悄创建了新层叠上下文。静态定位（position: static）的元素，z-index完全被忽略。
检查开发者工具的「Computed」面板：如果z-index显示为 auto 或灰掉，说明它没被激活。往上逐级看父元素是否带以下任一属性：transform（哪怕只是translateZ(0)）、opacity: 0.99、filter、will-change。只要触发其一，子元素的z-index就只能在该父容器内比大小。
- 临时移除可疑父级样式，确认是否恢复预期层级
- 若必须保留（如动画优化），就把需要提层的元素“提”到更高层级容器中，而不是硬调子元素的
z-index - 用
position: relative给挂载点（如#overlay-root）显式设定位，避免 Portal 挂到body后因body无定位而错层
变量怎么声明才真正可控：作用域、命名和数值设计
--z-modal: 1000写在:root里看似方便，但一旦弹窗组件升级这个值，侧边栏菜单也可能被意外顶起——所有引用它的组件都跟着动。更稳妥的是按功能域就近定义变量。
比如模态框组件内部写：.modal { --z-element: var(--z-modal, 1000); z-index: var(--z-element); }；下拉菜单则用--z-dropdown，Toast 用--z-toast，彼此隔离。
立即学习“前端免费学习笔记（深入）”；
- 禁止跨模块复用同名变量，哪怕值相同——
@z-focus-ring在 Button 和 Modal 中语义不同，将来必然分家 - 数值要预留间隙：相邻层级至少差 10（如
--z-tooltip: 300，--z-modal: 900），给中间插入新层留余地 - 别用
calc(var(--z-base) + 10)嵌套太深，旧版 Safari 对calc+var()嵌套支持不稳定
JS 动态读写 CSS 变量时的坑：字符串 vs 数值
通过 JS 修改层级很常见（比如主题切换时动态降级弹窗），但getComputedStyle().getPropertyValue('--z-modal')返回的是字符串，直接拿去比较会出错：
const zIndexStr = getComputedStyle(document.documentElement).getPropertyValue('--z-modal'); // "1000"
console.log(zIndexStr > 900); // true —— 这是字符串比较，"1000" > "900" 成立
console.log(+zIndexStr > 900); // true —— 转数字才可靠
console.log(parseInt(zIndexStr, 10) > 900); // true —— 更安全
- 用
document.documentElement.style.setProperty('--z-modal', '1200')写入没问题，但读取后做数值运算前必须显式转整型 - 避免在同一个选择器里既声明又使用变量，如
.card { --z-card: 10; z-index: var(--z-card); }——这会让复用变得困难，后续想提取--z-card就得重复声明 - Less/Sass 变量无法被 JS 读取，调试和运行时覆盖受限，优先选 CSS 自定义属性
第三方库冲突时，别碰 node_modules，改挂载点和作用域
Ant Design 或 Bootstrap 的z-index常通过预处理器变量控制，但你用 CDN 引入未编译 CSS 时，根本没法重定义它们的$zindex-modal。强行改node_modules不可维护，也不符合 CI/CD 流程。
更实际的做法是：把你的组件挂载到一个独立容器中，并确保该容器自身参与全局层叠排序。
- 创建专用挂载点：
<div id="overlay-root" style="position: relative"></div>，而不是依赖body - 在 SSR 场景下注意：
body初始无position，JS 挂载前可能出现短暂错层，提前在 HTML 中加style="position: relative" - 如果必须兼容老库，可对它的根类加
!important覆盖（仅限兜底），但长期应推动统一变量体系，而非打补丁
真正难的不是写多少个z-index，而是让每个值都有明确归属、可追溯、不越界。变量只是容器，关键在谁有权定义、谁负责维护、冲突时按什么规则裁决——这些往往藏在组件边界和协作约定里，而不是 CSS 文件中。
