移动端使用 mask-image 必须同时写 -webkit-mask-image 和 mask-image 双前缀，svg 遮罩需 url 编码且 fill 必须为 white，mask-size 必须设为 100% 100%，且应包裹在 div 中而非直接作用于 img。
mask-image 在移动端必须写双前缀
不加 -webkit-mask-image，Safari 和部分安卓 WebView 直接忽略整个声明；Chrome/Edge 虽支持标准 mask-image，但 Safari 16.4+ 仍依赖前缀渲染 SVG 遮罩。只写 mask-image 等于在 iOS 上完全失效。
正确写法必须同时存在：
.element {
-webkit-mask-image: url("data:image/svg+xml,%3Csvg...%3C/svg%3E");
mask-image: url("data:image/svg+xml,%3Csvg...%3C/svg%3E");
}
- 不能省略
-webkit-，哪怕只跑 iOS 17+ 也不行 - SVG 必须 URL 编码，不能用内联
<svg></svg>标签 - 渐变值同理：
-webkit-mask-image: radial-gradient(...)和mask-image: radial-gradient(...)都要写
用 SVG 作 mask-image 时 fill="white" 是硬性要求
移动端浏览器（尤其 Safari）对 SVG 的 fill 解析极敏感：填 black、#000 或透明色，整块区域都会被当“隐藏”；只有 fill="white" 或 fill="#fff" 才能确保可见。渐变或滤镜不影响这一规则——最终 alpha 值由浏览器按 white/black 映射决定。
-
<path d="M0,0 L100,0 L50,86 Z" fill="white"></path>✅ 闭合三角形可见 -
<path d="..." fill="black"></path>❌ 全黑 → 全透明，元素消失 - 用
fill="url(#grad)"时，渐变终点必须是#fff，不能是transparent
响应式遮罩必须显式设 mask-size: 100% 100%
移动端容器宽高常由 width: 100% 或 aspect-ratio 动态计算，mask-size 默认为 auto 时，Safari 会把它缩成 0×0，导致遮罩不可见；Firefox 则直接跳过该声明。
- 必须写
mask-size: 100% 100%强制拉伸匹配容器 - 搭配
mask-position: center防止偏移 - 避免用
cover或contain：位图遮罩可用，但 SVG/渐变在小屏上易拉伸变形 - 容器本身要有可计算尺寸，比如
width: 100%; aspect-ratio: 4/3;，不能全靠内容撑开
别在 ![]()
上直接加 mask，套一层 更稳
原生 <img> 的 intrinsic 尺寸和 CSS 渲染层耦合紧密，加 mask-image 后，iOS Safari 容易出现闪烁、错位或首次加载不触发遮罩的问题。
- 正确结构：
<div class="masked-container"><img src="..."></div>
- 给
.masked-container 设明确宽高或 aspect-ratio，再加 mask-image
- 若需点击穿透，注意
pointer-events: none 不影响 mask 下的事件捕获——遮罩区域仍可点，因为盒模型没变
实际最常漏掉的一点：mask-image 的遮罩计算只看最终 alpha 输出，而移动端浏览器对 SVG 中 fill 的解析逻辑比桌面端更严格——fill="white" 不是建议，是生效前提。
原生 <img> 的 intrinsic 尺寸和 CSS 渲染层耦合紧密，加 mask-image 后，iOS Safari 容易出现闪烁、错位或首次加载不触发遮罩的问题。
- 正确结构：
<div class="masked-container"><img src="..."></div> - 给
.masked-container设明确宽高或aspect-ratio，再加mask-image - 若需点击穿透，注意
pointer-events: none不影响 mask 下的事件捕获——遮罩区域仍可点，因为盒模型没变
fill 的解析逻辑比桌面端更严格——fill="white" 不是建议，是生效前提。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
