iOS Safari中mask-image生效需同时满足四条件：-webkit-mask-image与mask-image成对且值一致；仅支持单行base64内联SVG（含URL编码）；SVG内部fill必须为#fff；img元素须显式设width、height和display:block。
mask-image 在 iOS 上根本不会显示，除非满足这四个硬性条件
直接给 <img> 加 mask-image 几乎必现白屏，Safari 不报错、不警告、不渲染——它只是默默跳过。真正起作用的写法必须同时满足：
-
-webkit-mask-image和mask-image必须成对出现，且值完全一致 - 不能用
url('/mask.svg')这类外部路径，Safari 对 URL 解析极其脆弱（#、空格、未编码的<都会导致静默失败） - 必须用单行 base64 内联 SVG，且所有
<、>、"都要 URL 编码（例如%3Csvg） - SVG 内部
<path>必须闭合（以Z结尾），且fill="#fff"——不是透明、不是 #000、不是渐变，就是纯白
给 img 标签加 mask 的前提：尺寸和 display 都得“钉死”
现代框架（如 Bootstrap、Tailwind）默认给 <img> 设 height: auto 或 display: inline，这会让 Safari 拒绝计算 mask 区域。你得显式覆盖：
- 必须设
width和height（不能只靠max-width: 100%） - 必须设
display: block（inline 元素在 Safari 中 mask 渲染不可靠） - 如果头像来自 CDN，优先用 data URI 内联 SVG，避开 CORS 导致的 mask 加载失败
- 显式声明
mask-origin: border-box和mask-clip: border-box，否则各浏览器默认行为不一致
mask-image 不等于 clip-path：热区错位是设计使然，不是 bug
这是最容易被忽略的本质问题：mask-image 只控制像素是否绘制，不改变盒模型边界。用户看到的是心形，但 getBoundingClientRect() 返回的仍是原始矩形，点击事件也按矩形分发。
- iOS 上点“心尖”可能触发左侧 tab，点“心底空白”反而跳转 —— 这不是渲染 bug，是 spec 规定
- 滚动时
position: fixed元素上的 mask 会偏移（WebKit 已知问题，无完美绕过） - 高清屏下 mask 边缘常有 1px 半透明晕染，因为未按
window.devicePixelRatio缩放遮罩图 - 如果你需要精确点击、缩放响应或滚动跟随，
clip-path: path()才是唯一可控出口（iOS Safari 16.4+、Chrome 100+ 稳定支持）
真机测试前必须检查的三件事
哪怕代码在桌面 Chrome 里跑得飞起，真机上也可能全黑或错位。上线前务必确认：
立即学习“前端免费学习笔记（深入）”；
- SVG 是否声明了
viewBox，且其宽高比与目标容器严格一致（例如头像 200×200，viewBox="0 0 200 200"） - 是否用了
mask-mode: luminance（避免 Chrome 当亮度处理、Firefox 当 Alpha 处理导致灰度解释不一致） - 是否为降级写了 fallback：
clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%)，否则老 iOS 直接显示完整矩形
真正难的不是画出形状，而是让形状在横竖屏切换、键盘弹出、滚动锚点、不同 DPR 屏幕下都保持对齐、可点、不闪动。这些细节里，mask-image 几乎全军覆没。
