z-index工具类必须配合position属性才生效，否则无效；层级控制失效常因父容器创建新堆叠上下文；响应式需按断点分层设计；动态插入元素应通过JS计数器管理z-index。
z-index 工具类必须配合定位属性才生效
直接给元素加 z-index 类但没设 position，样式完全无效——这是最常踩的坑。CSS 规范规定：z-index 只对「定位元素」（position 值为 relative、absolute、fixed 或 sticky）起作用。
实操建议：
- 工具类命名应隐含定位要求，比如
z-10配套提供relative或relative-z类，避免单独使用 - 用 CSS 自定义属性统一管理层级基数，便于后期调整：
:root { --z-base: 0; --z-modal: 1000; --z-toast: 2000; } - 避免用过大的数值（如
z-9999），不同项目间难以协调，也容易在嵌套中意外突破父级 stacking context
层级控制失效往往是因为创建了新的 stacking context
即使 z-index 数值更大，如果父容器设置了 opacity: 0.99、transform: translateZ(0)、will-change: transform 或 filter 等属性，就会创建独立 stacking context，子元素的 z-index 只在该上下文中比较，无法越过父级和兄弟元素竞争。
排查要点：
立即学习“前端免费学习笔记（深入）”；
- 用浏览器开发者工具检查目标元素的「Computed」面板，看
z-index是否被标记为auto（说明未生效）或实际值是否被父级截断 - 临时移除父级的
transform、opacity、filter等属性，确认是否恢复预期叠放 - 若必须保留这些视觉效果，改用
isolation: isolate显式隔离，或把需要高层级的元素提升到同级 DOM 位置（如挂到body下）
响应式 z-index 工具类需按断点分层设计
移动端弹窗和桌面端侧边栏可能需要不同的层级优先级。硬编码固定值会导致小屏下 toast 被 modal 挡住，或大屏下 tooltip 被 header 盖住。
.z-0 { z-index: 0; }
.z-10 { z-index: 10; }
.z-20 { z-index: 20; }
@media (min-width: 768px) {
.md\:z-50 { z-index: 50; }
}
@media (min-width: 1024px) {
.lg\:z-100 { z-index: 100; }
}
关键点：
- 基础层级（如
z-0~z-20）覆盖常规布局流；断点层级（md:z-50）专用于交互组件 - 避免在媒体查询内重定义同一类名，否则会覆盖而非增强
- 所有断点层级值必须严格大于其对应的基础层级，防止响应式切换时出现反向覆盖
JavaScript 动态插入元素时 z-index 容易失控
通过 document.createElement 创建的 toast、tooltip 等浮层，若只靠工具类设置 z-index，在多实例并存时极易堆叠错乱——比如后创建的 toast 反而被先创建的盖住。
稳妥做法：
- 维护一个全局计数器，每次插入新浮层时递增并写入
style.zIndex：let zIndexCounter = 1000; function createToast() { const el = document.createElement('div'); el.className = 'toast z-10'; el.style.zIndex = String(++zIndexCounter); document.body.appendChild(el); } - 不依赖工具类的
z-index值，而是用 JS 控制真实层叠顺序，工具类仅作兜底或语义化标识 - 销毁元素时不必重置计数器，但要注意长期运行页面中数值溢出风险（一般到百万级才需考虑）
z-10 z-20 类，而是理解 stacking context 的边界在哪里、何时会被意外切断，以及动态场景下如何让层级逻辑可预测。多数“z-index 不生效”问题，根源都在父级或祖先节点上。 
