根本原因是body默认position:static导致z-index无效，需显式设position:relative激活层叠上下文；同时scoped样式使:root变量失效，应移至全局样式；transform父容器也会创建新包含块干扰fixed定位。
弹窗用 createPortal 挂到 body 后 --z-modal 不生效
根本原因不是变量没定义，而是挂载后脱离了原组件的继承链——:root 里声明的变量虽全局可见，但第三方弹窗（如 uni-modal）或自研组件常依赖父容器变量，而 body 默认没设 position，导致 z-index: var(--z-modal) 虽解析成功却无层叠资格。
- 检查
body的position值：DevTools 中看Computed面板，若position是static（默认），则z-index无效，哪怕变量值正确 - 给
body显式加position: relative（仅需这一条，无需z-index），就能激活其作为定位上下文的资格，让挂载进来的弹窗能参与全局层叠计算 - 避免在
body上重复声明变量：比如body { --z-modal: 1000; }会覆盖:root的同名变量，且可能被其他样式表后加载覆盖；应统一保留在:root，只补position
z-index: var(--z-modal) 在弹窗里显示为 auto
这是最典型的“有变量、无效果”信号——说明该元素压根没进入层叠上下文参与比较。常见于弹窗内部子元素漏设定位，或父级触发了新层叠上下文。
- 逐级检查弹窗 DOM 结构：从最外层弹窗容器开始，确认每个要用
z-index的节点都设置了position: relative/absolute/fixed/sticky - 警惕
transform：如果弹窗父容器（比如一个带transform: scale(0.95)的遮罩层）存在，它会创建新包含块，导致子元素的fixed行为异常，z-index只在该块内比大小 - 不要依赖
transform: translateZ(0)强制提升层级：它会创建独立层叠上下文，把子元素“关”在里面，外部变量依然无法穿透影响
style scoped 导致 :root { --z-modal: 1000 } 不被读取
Vue 或类似支持 scoped 的框架中，<style scoped></style> 会自动给选择器加属性哈希，:root 变成 :root[data-v-xxx]，而 body 没这个属性，变量自然失效。
- 把变量声明移到非
scoped的全局样式文件中（如main.css或index.html的<style></style>标签内） - 如果必须在组件内管理主题变量，改用
:host（Web Components）或直接在弹窗组件根元素上声明：<div class="modal" style="--z-modal: 1000"> - React 用户可用 JS 动态注入：
document.documentElement.style.setProperty('--z-modal', '1000')，确保执行时机在 portal 挂载前
移动端 fixed 弹窗层级被遮挡且 z-index 无效
iOS Safari 对 fixed 元素的层叠处理更严格，尤其当页面有 transform、will-change 或滚动容器嵌套时，z-index 容易被降级或忽略。
立即学习“前端免费学习笔记（深入）”；
- 确认弹窗容器是否被套在
transform父级中：比如整个页面包裹了div#app { transform: translateZ(0); }，此时fixed弹窗实际相对于该div定位，而非视口 - 用
position: absolute替代fixed并配合top: env(safe-area-inset-top)，再手动监听scroll和resize更新top/left值（适合需要精确控制的场景） - 终极兜底：在
body上加touch-action: manipulation，减少 iOS 对滚动和点击事件的歧义判断，间接提升 fixed 渲染稳定性
body 缺少 position、scoped 锁死作用域、transform 悄悄重置包含块，这三个地方漏查一个，变量就白定义。 
