必须同时写mask-image和-webkit-mask-image，且标准属性在前、WebKit前缀在后，否则Safari会静默失效；Chrome/Safari因未将mask-image列为无前缀稳定特性，仅写标准属性会被跳过，Firefox则忽略前缀但要求data URL或内联SVG。
必须同时写 mask-image 和 -webkit-mask-image，且顺序不能颠倒——标准属性在前、WebKit 前缀在后，否则 Safari 会静默失效。
为什么只写 mask-image 在 Chrome/Safari 里完全没反应
Chrome（含 Edge）和 Safari 当前（2026 年中）仍未将 mask-image 列为无前缀稳定特性。浏览器解析器遇到标准属性直接跳过，除非你显式提供 -webkit-mask-image。实测 Chrome 122+ 中仅保留 mask-image: url("data:image/svg+xml,...")，computed 面板里该值显示为 none，页面无任何遮罩效果。
-
mask-image不是“可选前缀”，而是硬性依赖项：漏掉-webkit-，Chrome/Safari 就不渲染 - Firefox 完全忽略
-webkit-mask-image，所以标准属性也得保留，不能只靠前缀 - 声明顺序错误（比如先写
-webkit-mask-image）会导致 Safari 某些版本（如 iOS 15.6）级联解析失败，两者都被跳过
mask-image 的值类型与浏览器差异
不是所有合法的 <image> 值都能跨浏览器生效。关键限制在于：Firefox 不支持外部 SVG 文件，Safari 对渐变颜色语义极其敏感。
- SVG 遮罩必须用
data:image/svg+xml,URL 编码，且内部<path>或<rect>的fill必须为white（不能省略或设为black） - 渐变类写法（
linear-gradient()）在 Firefox 中被整体忽略；Safari 要求起止色必须是纯灰度（#000/#fff），transparent会被转成#000导致全显 - PNG 遮罩图在 Firefox 中按 luminance 模式解析：alpha 通道被忽略，透明区域等价于黑，结果常为全黑失效——应改用白底黑镂空，或确保 PNG 是灰度图
必须配套设置的三个属性
只写 mask-image 和前缀远远不够。浏览器默认行为会让遮罩图缩放为 0×0、平铺满屏或居中裁切，实际几乎不可见。
立即学习“前端免费学习笔记（深入）”；
-
mask-size: 100% 100%（或cover/contain）：auto在各浏览器表现不一致，等于没设 -
mask-repeat: no-repeat：默认repeat，小图标会密密麻麻铺满整个容器 -
mask-position: center（或按需调整）：若容器宽高比与遮罩图不匹配，cover会裁边，此时需换contain或手动设偏移
Firefox 下静默失效的典型陷阱
Firefox 不报错、不警告、不 fallback，只把无效声明当不存在。最常踩的坑是用了已废弃的简写语法，或误信了“mask 单值”能通用。
- ❌ 错误：
mask: url("mask.svg")—— Firefox 直接跳过整条规则，computed 面板中mask-image显示为none - ❌ 错误：
mask-image: url("mask.svg")（外部文件）—— Firefox 静默失败，必须用 data URL 或内联<mask>元素 - ✅ 正确：
mask-image: url("data:image/svg+xml,%3Csvg%3E%3Ccircle%20fill=%22white%22%20r=%2250%22/%3E%3C/svg%3E");
真正难的不是写对一行 CSS，而是每张遮罩图都要按三套引擎逻辑分别验证：WebKit 看前缀和 SVG fill，Firefox 看 data URL 和 luminance 语义，Chrome 看前缀是否存在且顺序正确——缺一不可。
