一个 H5 装饰按钮在 Android WebView 和 iOS Safari 上的两次渲染排查

一个移动 H5 页面里有个固定在右下角的小按钮。按钮本身不复杂：圆角胶囊、渐变底色、生日图标、右侧气球纹理、左上角高光纹理，收起时会变成一个窄按钮。

麻烦点在装饰层。为了贴近设计稿，按钮里用了负坐标纹理、mix-blend-mode、半像素描边、overflow: hidden、圆角和动画。Chrome 桌面看起来正常，不代表移动 WebView 也稳定。这个按钮先后暴露了两个问题：

Android WebView 上，按钮左上角多出一块异常区域；隐藏 .birthday-privilege-entry__texture 后，异常消失。
iOS Safari 上，Chrome 正常，但按钮左侧边缘像多了一条边框；最后通过显式 WebKit mask 稳住圆角裁剪。

最后稳定下来的写法大概是这样：

.birthday-privilege-entry {
  overflow: hidden;
  border-start-start-radius: 100px;
  border-start-end-radius: 100px;
  border-end-start-radius: 100px;
  border-end-end-radius: 100px;
  isolation: isolate;

  // Safari 会把 blend-mode 纹理作为独立图层合成，显式 mask 可以避免它突破圆角裁剪。
  -webkit-mask-image: -webkit-radial-gradient(#fff, #000);
}

这次异常出现在混合模式、裁剪和图层合成叠加后的视觉边界上。普通布局错位或 z-index 写小了，都不足以解释两个平台的现象。

真实结构

按钮模板可以简化成这样：

<div class="birthday-privilege-entry">
  <img class="birthday-privilege-entry__texture" src="./assets/entry-texture.png" />
  <img class="birthday-privilege-entry__balloon" src="./assets/entry-balloon.png" />
  <img class="birthday-privilege-entry__icon" src="./assets/entry-icon.png" />
  <span class="birthday-privilege-entry__text">Claim your birthday gift</span>
</div>

样式里最关键的是这几块：

.birthday-privilege-entry {
  position: fixed;
  bottom: 60px;
  inset-inline-end: 16px;
  width: 151px;
  height: 48px;
  overflow: hidden;
  border-start-start-radius: 100px;
  border-start-end-radius: 100px;
  border-end-start-radius: 100px;
  border-end-end-radius: 100px;
  background: linear-gradient(107.798deg, #3f2504 2.1369%, #8c550f 48.206%, #5d3a0b 100.21%);
  isolation: isolate;
}

.birthday-privilege-entry::after {
  position: absolute;
  inset: 0;
  z-index: 4;
  border: 0.5px solid #fff;
  border-start-start-radius: inherit;
  border-start-end-radius: inherit;
  border-end-start-radius: inherit;
  border-end-end-radius: inherit;
  box-sizing: border-box;
  content: '';
  mix-blend-mode: soft-light;
  pointer-events: none;
}

.birthday-privilege-entry__texture {
  position: absolute;
  z-index: 1;
  top: -80.34px;
  inset-inline-start: -56.17px;
  width: 167.6px;
  height: 152.25px;
  opacity: 0.4;
  mix-blend-mode: color-dodge;
}

这段代码有几个风险点：

.birthday-privilege-entry__texture 的位置是负坐标，它大部分区域其实在按钮外面。
父级靠 border-radius + overflow: hidden 把外面的纹理裁掉。
纹理用了 mix-blend-mode: color-dodge。
伪元素描边用了 border: 0.5px 和 mix-blend-mode: soft-light。
父级用了 isolation: isolate，希望把混合范围限制在按钮内部。

MDN 的层叠上下文文档列出的高风险信号里，正好包括 mix-blend-mode、transform、filter、mask / mask-image 和 isolation: isolate。这些属性会改变元素参与层叠和绘制的方式。单独使用时问题不大，叠在移动端 WebView 的圆角裁剪里，就会把问题推到浏览器合成阶段。

MDN 的 compositing and blending 文档把混合模式描述为元素背景、边框、内容和父级背景之间的混合关系。这里让浏览器把两个视觉层按某种模式混在一起，并不是简单给元素涂一个颜色。

Android：隐藏 texture 后恢复正常

Android 那次的现象是按钮左上角多出异常色块。设备 UA 里能看到 Android 12、Chrome 95、wv，也就是 App 内 WebView 环境。

最有效的隔离动作是：

.birthday-privilege-entry__texture {
  visibility: hidden;
}

隐藏 texture 后异常消失，说明异常和这层强相关，排查范围缩到了它的样式及与其他层的交互。这个结果还不能单独证明素材或 Android WebView 有问题，也不能排除 texture 与背景、描边或裁剪共同触发异常，需要继续分别隔离：

/* 只保留图片，不混合 */
.birthday-privilege-entry__texture {
  mix-blend-mode: normal;
}

/* 保留混合，但让它不跑到圆角外面 */
.birthday-privilege-entry {
  -webkit-mask-image: -webkit-radial-gradient(#fff, #000);
}

/* 视觉允许时，直接把纹理预合成到素材里 */
.birthday-privilege-entry__texture {
  display: none;
}

如果 mix-blend-mode: normal 后恢复，说明实时混合是关键触发点。如果补 mask 后恢复，说明父级裁剪边界在合成阶段不够稳定。如果预合成素材后恢复，说明运行时 blend 本身就不是这个 UI 必须保留的能力。

这次需要保留纹理效果，所以没有直接删图，而是尝试调整父级裁剪。如果装饰可以舍弃，移除纹理也是有效方案；是否保留，取决于设计要求和设备上的验证结果，不必为了保住一层 CSS 继续叠兼容写法。

iOS：Chrome 正常，Safari 左边多出边框

iOS 那次更像典型 WebKit 视觉边界问题。桌面 Chrome 或 Android Chrome 看着没问题，Safari 上按钮左侧却像多了一条边框。

这个现象有两个候选触发点：

::after 伪元素用了 border: 0.5px solid #fff 和 mix-blend-mode: soft-light。
texture 作为负坐标装饰层参与混合，WebKit 可能把它作为单独图层处理。

0.5px 本身可以用。它叠在圆角裁剪、混合模式、设备像素比和 WebKit 合成层里以后，已经不再是普通静态描边。Safari 最后看到的可能是一条被合成后更明显的左侧亮边，而不是一个被柔化的 soft-light 描边。

稳定版本做了两件事：

.birthday-privilege-entry {
  overflow: hidden;
  border-start-start-radius: 100px;
  border-start-end-radius: 100px;
  border-end-start-radius: 100px;
  border-end-end-radius: 100px;

  // Safari 会把 blend-mode 纹理作为独立图层合成，显式 mask 可以避免它突破圆角裁剪。
  -webkit-mask-image: -webkit-radial-gradient(#fff, #000);
}

.birthday-privilege-entry::after {
  border: 0.5px solid #fff;
  border-start-start-radius: inherit;
  border-start-end-radius: inherit;
  border-end-start-radius: inherit;
  border-end-end-radius: inherit;
  mix-blend-mode: soft-light;
}

第一件事是给父级显式 mask。overflow: hidden 是布局裁剪，mask-image 是图像遮罩。MDN 的 mask-image 文档说明，mask 会根据 alpha 或 luminance 决定元素哪些区域可见。这里用一个实心 radial gradient，不做渐隐效果，只是给 WebKit 一个更明确的圆角裁剪边界。

第二件事是伪元素描边的圆角逐个继承父级 logical corner。这样收起态改变右侧圆角时，描边层也跟着变，不会留下自己的旧圆角或边界。

这类修法最好保留注释。-webkit-mask-image: -webkit-radial-gradient(#fff, #000) 看起来像老式 hack；没有 Why 注释，后续 review 很容易把它删掉。

最小 playground

这里放了一个自包含 playground，移动端可以直接扫码打开：

打开 playground

playground 里有四个模式：

风险组合：负坐标 texture、color-dodge、半像素 soft-light 描边和圆角裁剪同时存在。
隐藏 texture：模拟 Android 那次的最小隔离动作。
加 WebKit mask：模拟最终稳定修法。
预合成思路：去掉运行时 blend，用普通背景和 inset shadow 表达接近效果。

这个 playground 不承诺在所有设备上都复现异常。它的用途是让读者快速切换变量，理解这类问题为什么要从 texture、blend、border 和 mask 几个方向拆，而不是看到 Chrome 正常就结束排查。

为什么不是单纯的 border 问题

如果只看 iOS 截图，很容易把它归成「左侧 border 没裁好」。但 Android 那次隐藏 texture 后恢复，说明问题不只在 ::after 描边层。

更合理的模型是：

WebKit 的 Layers 文章解释过，浏览器不会把 DOM 元素逐个直接画到屏幕上。元素会先绘制到 layers / surfaces，再按顺序合成；元素类型、CSS 属性和图层交互都可能生成新的 layer。这样看，Android 和 iOS 的两个现象就能放到同一条线上：它们都是复杂装饰层在合成和裁剪边界上的问题，只是不同引擎暴露出来的位置不一样。

下次怎么排查

移动 WebView 边缘异常时，排查顺序先从最小隐藏层开始：

先找最小隐藏层。把纹理图、伪元素、阴影层、描边层逐个 visibility: hidden，确认隐藏哪一层后恢复。
再关高风险声明。优先关 mix-blend-mode、filter、opacity、transform、border: 0.5px、overflow: hidden。
检查图片本身。看素材是否有透明底、半透明边缘、暗色底、非整数尺寸或被 CSS 拉伸。
检查裁剪边界。border-radius + overflow: hidden 不稳定时，尝试 -webkit-mask-image 或 clip-path: inset(0 round ...)。
评估预合成。装饰层只是为了接近设计稿时，运行时 mix-blend-mode 未必值得保留。把高光、纹理、描边合进 PNG / WebP，通常比让移动端实时混合更稳。

如果能连接 Safari Web Inspector，可以打开 Layers 视图看相关元素是否被拆成独立合成层。WebKit 的 Layers 工具本来就是为了观察 layer 创建原因、绘制次数、内存成本和合成顺序。

修法选择

保留原有视觉、简化运行时效果和预合成素材，改动成本不同。可以按侵入程度从低到高尝试：

方案	适用场景	风险
给父级补 `-webkit-mask-image`	视觉效果必须保留，问题集中在圆角裁剪边缘	增加一条兼容性写法，需要注释解释
把 `border: 0.5px` 换成 inset shadow	描边只是轻微质感，不强依赖 blend	视觉和设计稿可能有细微差异
去掉运行时 `mix-blend-mode`	装饰层只是高光、纹理、氛围	需要重新确认设计效果
预合成素材	移动端稳定性优先，装饰层不需要动态变化	后续改视觉要重新出图

这次选择的是第一档：保留视觉效果，用 mask 明确裁剪边界，并在代码里写清楚原因。如果后续某个设备仍然异常，就应该往「预合成素材」方向走，而不是继续在运行时叠更多 blend / filter。

后面怎么记

这个按钮的问题不在尺寸，也不在文案，而在装饰层太复杂。mix-blend-mode、负坐标纹理、半像素描边、圆角裁剪和移动端 WebView 合成叠在一起后，Android 和 iOS 都可能在边缘处暴露不同问题。

排查时最有用的动作是先隐藏一层，确认异常跟谁强相关，再决定要不要加兼容写法。Android 那次隐藏 texture 后恢复，说明 texture 或它触发的合成路径是关键线索；iOS 那次给父级补 WebKit mask 后恢复，说明显式裁剪边界能让 Safari 的合成结果稳定下来。

后续再做这类 H5 装饰按钮时，运行时视觉效果要克制一点。能用普通背景和 inset shadow 表达的，不要急着上 blend；必须上 blend 时，把裁剪边界、注释和实机验证一起补上。

iOS WebKit 中 transform 和 z-index 的一次层级闪烁排查上一篇

Codex Skill 里不应该明文保存密钥下一篇