在微信小程序里实现自定义 Modal 时，层级穿透通常是这么出现的：弹窗已经显示，手指点击遮罩空白区域，结果底页某个按钮也触发了 tap 事件；或者手指在弹窗上滑动，底下页面跟着滚动。很多实现会把希望寄托在 z-index 上，但问题根源往往不是 z-index 不够，而是遮罩层没有完整接收命中事件，或者事件绑定方式没有拦住冒泡。
要彻底解决这个问题，需要先理解微信小程序的命中测试和事件模型。点击事件先经过捕获阶段，然后到达目标节点，再冒泡回根节点。某个坐标最终命中哪个节点，取决于该坐标上最上层的可接收事件的组件。因此只要全屏遮罩层真实覆盖在下层内容之上，并且没有被 pointer-events 设为 none，下层元素就不会直接收到点击。catchtap 的作用是在冒泡阶段阻止事件继续向上传递，而弹窗内容被点击时如果不希望触发遮罩关闭，也需要拦截冒泡。下面从命中机制、事件绑定和滚动防护几个角度展开。
先厘清层级穿透的两类原因
微信小程序中的普通组件使用 WebView 渲染，多数情况下 z-index 能决定显示层级。但真实项目里仍然会遇到点击穿透，一般可以归为两类。第一类是遮罩层本身没有完整覆盖或没有接收事件。例如有开发者为了让弹窗下方的页面看起来还能点击，给遮罩层写了 pointer-events: none，这会让点击直接穿过遮罩落到下层元素。还有的情况是遮罩层只包裹了弹窗主体，没有覆盖整个屏幕，弹窗主体之外的区域仍然是底页元素，自然会被点击到。
第二类是原生组件导致的层级异常。微信小程序中的 video、map、canvas、textarea、camera 等组件在部分平台上仍然具备原生层级，可能会覆盖在普通 <view> 之上。即使你的自定义 Modal 使用 position: fixed 并且 z-index 很高，这些原生组件仍可能显示在弹窗上方，或者出现点击落到原生组件的现象。解决这类问题通常要使用 cover-view、cover-image，或者确认客户端已经开启同层渲染。同层渲染可以降低原生组件穿透概率，但在低版本基础库或特定机型上仍可能存在差异，所以排查时需要把基础库版本和机型因素考虑进来。
还有一种容易忽略的情况是弹窗内部点击冒泡到遮罩层。假设遮罩层绑定了关闭弹窗的 catchtap，弹窗内容区域只绑定了业务按钮的 bindtap。由于事件会从按钮冒泡到弹窗容器，再冒泡到遮罩层，如果弹窗容器没有拦截，点击内容区域就会触发遮罩的关闭逻辑。这个问题虽然不属于下层元素的点击穿透，但表现上会造成弹窗交互混乱，排查时经常被归到层级问题里。
全屏遮罩加 catch 事件实现点击拦截
阻止下层元素点击最稳妥的方式，不是给下层页面加 pointer-events，也不是把下层按钮全部禁用，而是让遮罩层成为一个真实的全屏命中层。具体做法是：在弹窗显示时渲染一个铺满屏幕的 <view>，设置 position: fixed 并让 left、top、right、bottom 全部为 0，背景色可以使用半透明黑。这个遮罩层只要没有设置 pointer-events: none，它就会拦截所有落在弹窗区域之外、遮罩范围内的点击，下层按钮自然收不到事件。
事件绑定方面，推荐在遮罩层上使用 catchtap 而不是 bindtap。catch 前缀可以阻止事件继续冒泡到父级，避免点击遮罩时触发页面根节点上的一些全局逻辑。遮罩层的 catchtap 可以直接绑定关闭弹窗函数，也可以绑定空函数，取决于你是否需要点击遮罩关闭。若需要点击遮罩关闭，就绑 catchtap="closeModal"；如果只希望拦截点击但点遮罩不关闭，就绑 catchtap="noop"。下面是一个完整的基础结构。
<view class="page">
<button bindtap="openModal">打开弹窗</button>
<view class="content">页面内容区域</view>
</view>
<view wx:if="{{visible}}" class="modal-mask" catchtap="closeModal" catchtouchmove="noop">
<view class="modal-body" catchtap="noop">
<view class="modal-title">确认操作</view>
<button type="primary" bindtap="confirm">确认</button>
<button bindtap="cancel">取消</button>
</view>
</view>
这段结构中，遮罩层 modal-mask 负责覆盖整个屏幕并接收点击。弹窗主体 modal-body 额外绑定了一个 catchtap="noop"，目的是阻止内容区域的点击冒泡到遮罩层。否则点击弹窗里的按钮时，事件会先经历按钮自身的 bindtap，然后一路冒泡到 modal-body，再到 modal-mask，最终触发 closeModal，导致弹窗内容区点击也会关闭弹窗。多写一个空函数并不复杂，但可以避免很多交互上的意外。
在 WXSS 中，遮罩层需要保证覆盖全屏，并且不要使用 pointer-events: none。弹窗主体如果曾经设置过 pointer-events: none 为了穿透某些场景，也需要恢复为 auto。示例样式如下。
.modal-mask {
position: fixed;
left: 0;
top: 0;
right: 0;
bottom: 0;
background: rgba(0, 0, 0, 0.5);
z-index: 1000;
display: flex;
align-items: center;
justify-content: center;
}
.modal-body {
width: 80%;
background: #fff;
border-radius: 16rpx;
padding: 32rpx;
pointer-events: auto;
}
对应的 JS 逻辑也不复杂。openModal 负责显示弹窗，closeModal 负责关闭，noop 作为空函数阻止冒泡。confirm 和 cancel 里除了业务处理外，通常也需要在最后关闭弹窗。这个示例中 noop 函数体为空，但它足以拦截事件，不需要返回 false 或调用 stopPropagation，因为 catch 前缀已经承担了阻止冒泡的职责。
Page({
data: {
visible: false
},
openModal() {
this.setData({ visible: true });
},
closeModal() {
this.setData({ visible: false });
},
noop() {},
confirm() {
console.log('confirm');
this.setData({ visible: false });
},
cancel() {
this.setData({ visible: false });
}
});
如果担心部分场景下 catch 冒泡拦截仍然不够，可以采用捕获阶段拦截。微信小程序支持 capture-catch:tap，表示在捕获阶段监听并阻止事件继续传递。将遮罩层改为 capture-catch:tap="maskTap" 后，点击遮罩时事件在捕获阶段就被拦截，不会继续向下层分发。不过对于已经全屏覆盖的普通 view 来说，正常开发中使用 catchtap 已经足够，capture-catch 更适用于复杂组件嵌套或需要提前阻断的交互场景。
阻止滚动穿透与返回键穿透
层级穿透不只表现为点击落到下层按钮，滚动穿透同样会让用户感觉弹窗像浮在页面上却没有隔离。用户在弹窗内容上滑动时，如果底层页面跟着滚动，说明 touch 事件没有被遮罩层拦下。解决方案是在遮罩层绑定 catchtouchmove="noop"。这个绑定会阻止触摸移动事件继续冒泡，并且在多数小程序基础库中能够有效阻断底部页面滚动。代码里已经加上了这一行，noop 函数保持为空即可。
如果页面的滚动发生在更底层的 scroll-view 或页面本身，仅靠 catchtouchmove 有时仍然不能完全锁住。此时可以借助微信小程序提供的 page-meta 组件。将 page-meta 放在页面根部，通过 page-style 动态设置 overflow: hidden，可以从页面级别禁止滚动。示例写法如下。
<page-meta page-style="{{visible ? 'overflow: hidden;' : ''}}"></page-meta>
small 程序中 page-meta 的作用是设置页面属性，动态绑定 page-style 可以在弹窗打开时锁定页面滚动，弹窗关闭时恢复。需要注意的是，page-meta 的兼容性在不同基础库版本上有所区别，如果项目需要兼容较老版本，可以把 catchtouchmove 作为主方案，page-meta 作为增强方案。对于弹窗内部独立的 scroll-view，不需要阻止其滚动，只要确保它的事件不会冒泡到遮罩层即可。
返回键穿透一般指安卓机在弹窗打开时按返回键，页面直接退出，而不是先关闭弹窗。微信小程序没有提供统一的返回键拦截 API，在页面栈中可以通过 onUnload 或 onBackPress 来处理，但 onBackPress 只在部分框架或自定义导航中可用。原生小程序页面目前没有标准 onBackPress。常见做法是使用 navigateTo 打开一个新页面作为弹窗，这样返回键会关闭弹窗页面而不是退出当前页，但会增加页面栈成本。另一个思路是在弹窗打开时记录状态，并在页面 onHide 或 onUnload 中判断是否需要阻止返回，不过这种方法体验一般。通常建议优先处理点击和滚动穿透，返回键问题根据业务复杂度单独设计。
原生组件场景与排查清单
当页面中存在 video、map、textarea 等原生组件时，自定义 Modal 可能直接被这些组件盖住，或者点击穿透到原生组件上。对于视频播放器这类场景，如果要在弹窗上显示覆盖内容，可以使用 cover-view 和 cover-image。cover-view 是覆盖在原生组件之上的文本视图容器，cover-image 用于显示图片。把弹窗遮罩和弹窗主体改为 cover-view 可以规避多数原生组件层级问题，但 cover-view 的样式能力有限，不支持复杂的布局和动画。因此如果弹窗交互非常复杂，可以考虑在弹窗展示时用 wx:if 隐藏底层的原生组件，或者用同层渲染代替。
排查层级穿透问题时，可以按以下顺序逐项确认。首先检查遮罩层是否真的铺满全屏，left、top、right、bottom 是否都被设置为 0，position 是否为 fixed。其次检查遮罩层及其父级是否设置了 pointer-events: none，如果有就需要移除或改为 auto。然后确认事件绑定是否使用了 catchtap 或 capture-catch，而不是普通的 bindtap。再检查弹窗主体是否绑定了 catchtap 阻止内部点击冒泡。最后观察页面是否存在原生组件，尤其是当前基础库是否支持同层渲染，必要时改用 cover-view 或隐藏原生组件。
还有一个常见误区是以为 catch 用来阻止下层兄弟节点接收事件。实际上小程序的 catch 只阻止事件向父级冒泡，并不能直接拦截兄弟节点的命中。下层元素之所以收不到点击，是因为全屏遮罩覆盖了它，命中测试只会选择最上层组件。所以解决问题的核心始终是让遮罩层完整、可见且能够接收事件，catch 只是在这个基础上避免事件继续传播。理解这一点后，再遇到弹窗相关交互问题，就不会盲目堆叠 z-index 或随意使用 catch，而是能快速定位到真正的层级原因。