z-index失效主因是父元素创建层叠上下文使子元素被“关进小房间”，而非数值过小；需检查transform、opacity、filter、position等隐式触发属性，并确保目标元素已定位且处于同一上下文。
层叠上下文冲突不是“样式没写对”，而是文档流被意外截断或升维——高性能前端架构里，z-index 失效、弹窗被盖、高亮错位，根源几乎都出在「谁创建了上下文」和「谁本该留在主文档流」上。
为什么 z-index 在组件库中突然失效
不是数值不够大，是你的目标元素已经掉进了一个被父容器悄悄封闭的 z 轴小房间。常见触发点：
-
transform: translateZ(0)或transform: scale(1)被加在编辑器 wrapper、Modal 根节点、甚至全局body上 —— 它们不显眼，但会立刻创建新层叠上下文 -
opacity: 0.99（哪怕只差 0.01）也会触发，尤其在动画过渡或渐变遮罩中高频出现 -
filter: blur(0)、will-change: transform同样静默生效，且 DevTools 的 computed 面板不会标红警告 - 父容器是
display: flex或grid，而子元素写了z-index: 1—— 此时父容器自动升级为层叠上下文，子元素的z-index只在内部比大小
position: relative 加在哪一层才真正有用
别直接给弹窗或 Tooltip 加 position: relative —— 它必须加在「所有浮动/覆盖内容的共同父容器」上，且这个容器得是文档流中的稳定锚点。
- 例如 Tiptap 编辑器：找
div[data-slate-editor]或div.prose，而不是你插进去的div.tooltip - 加之前确认它没被
transform或opacity污染；若有，先移除或用isolation: isolate切断污染 - 必须配
z-index（哪怕只是z-index: 0），否则position: relative不创建层叠上下文，后续子元素的z-index仍无效 - 若该容器本身需浮出页面（如全屏工具栏），
z-index值要高于其他 UI 层，但不必用 9999，按预设范围走更安全（比如editor-wrapper: 50,toolbar: 100）
isolation: isolate 不是开关，是边界声明
它不解决 z-index 冲突，也不让元素“飞出来”——它只告诉浏览器：“从我开始，下面所有 mix-blend-mode 和层叠顺序，都别往外串。”
立即学习“前端免费学习笔记（深入）”；
- 只对块级定位容器生效，
span、inline元素加了也白加 - 必须配合
position: relative或absolute才能参与层叠；单独加isolation: isolate不改变任何视觉 - 典型场景：代码块语法高亮 + 行号背景 + 编辑器底色，三者用了
mix-blend-mode: multiply，结果蓝字和灰色导航栏混出紫边 —— 给代码块外层加isolation: isolate，就只跟行号混，不跟导航栏混 - 注意拼写：
isolation: isolate，不是isolation: on或isolation: true，后者会被忽略
用文档流替代绝对定位来规避层叠陷阱
当多个组件需要堆叠又不想卷入 z-index 管理时，优先让它们自然留在文档流里，靠结构控制顺序。
- 垂直堆叠两个区域？用
display: flex; flex-direction: column，而不是给第二个加position: absolute; top: 100px - 工具栏悬浮在编辑区上方？把工具栏作为编辑器 wrapper 的第一个子元素，用
margin-bottom或gap控制间距，而非position: fixed - 需要局部覆盖（如选中文本高亮）？用
background-clip: text+-webkit-text-fill-color: transparent，避免插入额外 DOM 节点 - 所有依赖
position: absolute的组件，都应检查其最近的position: relative父容器是否意外成了层叠上下文 —— 这是最隐蔽的冲突源
真正难的不是写对某一行 CSS，而是判断「这个元素此刻属于哪个 z 轴空间」。DevTools 里看不出层叠上下文，只能靠行为反推：它的子元素能不能盖过兄弟？改它的 z-index 有没有对外部生效？—— 这才是高性能架构里最该花时间验证的地方。
