z-index: var(--z-modal)无效的首要原因是元素未设置非static定位；必须设为relative、absolute、fixed或sticky才能激活z-index，否则变量再正确也无用。
z-index: var(--z-modal)写了却没用，先看元素有没有定位
写了变量但层级不生效，90% 是因为目标元素压根没资格参与层叠。position: static（默认值）下，z-index 完全被忽略。必须显式设为 relative、absolute、fixed 或 sticky 才能激活。
检查开发者工具「Computed」面板：z-index 显示为 auto 或灰掉，说明没生效；position 值不是上述四种之一，就是根本原因。
常见误操作：
- 只在父容器设
position: relative，子元素没设定位，z-index白写 - 用
transform: translateZ(0)强制硬件加速，却忘了它也会触发新层叠上下文，把子元素“关”在里面 - 第三方组件（如
uni-modal）渲染到<body>下，但<body>没设position，导致挂载后失去统一调度基准
:root 里定义 --z-modal 不等于全局可用
变量声明位置不对，组件就根本读不到。在某个 <style scoped> 里写 :root { --z-modal: 1000; } 是无效的——scoped 样式会加属性选择器，:root 被限定在当前组件作用域内。
立即学习“前端免费学习笔记（深入）”；
真正全局生效的写法，只有一处：在项目顶层非 scoped 的 <style> 块中（如 Vue 的 App.vue、React 的 index.css），直接写：
:root {
--z-base: 0;
--z-toast: 800;
--z-dropdown: 900;
--z-modal: 1000;
--z-fullscreen: 1500;
}
UniApp 等跨端框架尤其要注意：uni.showToast 渲染的 DOM 在 <body> 下，如果变量只定义在某个 page 文件里，它完全看不到。
原生组件（如 uni-modal）class 名不固定，不能靠 .uni-modal 选择器注入样式，得用：
-
customStyle参数传入：z-index: var(--z-modal); position: relative; - 属性选择器：
[data-type="modal"] { z-index: var(--z-modal) !important; }（加!important防被内联样式覆盖）
数值设计要留空档，别迷信“越大越稳”
--z-modal: 999999 看似一劳永逸，实则埋下协作炸弹。一旦有人照抄这个值，后续新增中间层（比如半模态框、拖拽浮层）就只能硬挤或改已有值，很快撞上 2147483647（32 位整数上限）。
推荐分段+间隙策略：
- 基础层：
--z-base: 0，--z-header: 100，--z-sidebar: 200 - 浮层区：
--z-tooltip: 700，--z-dropdown: 900，--z-modal: 1000（相邻至少差 10） - 同组件内微调：
.modal__overlay { z-index: var(--z-modal); }，.modal__content { z-index: calc(var(--z-modal) + 10); }
注意：calc(var(--z-base) + 100) 在旧版 Safari 支持不稳定，建议只在 :root 层做一次计算，组件内直取 var(--z-modal-overlay)。
JS 动态改 z-index 变量时，别忘了重触发渲染
用 JS 改变量值：document.documentElement.style.setProperty('--z-modal', '1050')，但页面没反应？问题常出在浏览器没重绘。
getComputedStyle().getPropertyValue('--z-modal') 返回的是字符串，比较前得 parseInt()；更关键的是，CSS 自定义属性本身不触发重排，某些 Chrome 版本需要手动触发 reflow：
- 读取一个布局属性，比如
el.offsetHeight - 确保对应元素的 CSS 规则里真写了
z-index: var(--z-modal)，否则变量再改也没用 - 避免在同一个选择器里既声明变量又使用它：
.card { --z-card: 10; z-index: var(--z-card); }—— 这会让复用变得困难
真正容易被忽略的点是：变量只是数字容器，它不解决层叠上下文隔离问题。哪怕 --z-modal 值正确，只要弹窗被包裹在 opacity: 0.99 的卡片里，它就永远盖不过兄弟容器。调试时，永远先看「Layers」面板，再看变量。
