iOS Safari 中 mask-image 静默失效，需改用 clip-path: path() 并动态适配 DPR 与事件；若必须用 mask-image，则须内联 SVG、设 luminance 模式、cover 尺寸及黑白反色填充。
mask-image 在 iOS 上静默失效的典型表现
你写了 mask-image: url("heart.svg")，图标在 Chrome 里正常，在 iOS Safari 里直接“消失”——既不报错，也不渲染，控制台空空如也。这不是代码没生效，而是 Safari 拒绝解析该声明。常见触发条件包括：
• 缺少 -webkit-mask-image 双写声明
• URL 中含未编码的 #、空格或换行
• 遮罩图是外部 PNG 且带色彩配置文件（如 Adobe RGB）
• 元素本身没有 background-color 或 background-image，导致 mask 层无内容可遮罩
真正能跑通的移动端异形边缘方案只有 clip-path: path()
mask-image 不改盒模型边界，点击热区仍是矩形，iOS 下滚动还会偏移；而 clip-path: path() 直接裁剪元素几何形状，热区、布局、动画全部同步更新。当前（2026 年 10 月）已稳定支持：
• iOS Safari 16.4+（含所有主流 iPhone/iPad）
• Android Chrome 100+（覆盖绝大多数安卓设备）
• 必须降级 fallback：clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%)，否则老机型显示完整矩形
• 动态坐标建议用 JS 注入：clip-path: path("M20,0 Q50,-15 80,0 L100,20 L100,100 L0,100 Z")，避免硬编码像素值
如果非要用 mask-image 做背景边缘镂空，必须满足这四点
仅限静态、非交互、无滚动的卡片背景（比如首页 Banner 底部波浪边），且需严格满足：
• 内联 SVG：用 mask-image: url("data:image/svg+xml,%3Csvg...")，避免网络请求失败
• 显式设 mask-mode: luminance，否则 Firefox/Safari 解析逻辑不一致
• mask-size: cover + mask-position: center，禁用 contain（小屏下留白）
• SVG 中关键区域必须填 fill="black"（代表“显示”），镂空区留透明或 fill="white"（luminance 模式下白=全显，黑=全隐）
最常被忽略的细节：DPR 对齐与键盘弹出偏移
即使 clip-path: path() 跑通了，横竖屏切换、软键盘弹出、页面滚动锚点变化时，异形边缘仍可能错位。根本原因是路径坐标未按 window.devicePixelRatio 缩放，也未监听 resize 和 focusin/focusout 事件重算。真正落地的项目里，没人只写一次 path 值就完事——它得是动态计算的结果，且要预留至少 8px 交互间隙，防止手指点在凹口边缘触发误操作。
立即学习“前端免费学习笔记（深入）”；
