Safari 之所以会完全忽略 mask-image 声明，核心原因在于它必须同时声明 -webkit-mask-image 与 mask-image，而且书写顺序也有要求；如果只写标准属性，通常会被静默忽略。另外，URL 中包含未编码特殊字符、元素本身缺少可显示内容，或使用 transparent/rgba 渐变，也都会让遮罩效果失效。
为什么 Safari 完全忽略 mask-image 声明？
这是因为 Safari（包括当前主流的 iOS 与 macOS 版本）依然强依赖 -webkit-mask-image 私有前缀。如果只写标准属性 mask-image，在 Safari 里基本等同于没有写：不会报错、不会提示，也不会自动 fallback，而是直接把整条声明跳过。
正确做法是两个属性同时写，并且顺序不能乱：mask-image 写在前，-webkit-mask-image 写在后。如果顺序写反，或者少写其中任意一个，Safari 很可能直接不识别。
mask-image: url(mask.svg); -webkit-mask-image: url(mask.svg);✅-webkit-mask-image: url(mask.svg); mask-image: url(mask.svg);❌（部分 Safari ≤15.5 会出现级联失效）mask-image: url(mask.svg);❌（Safari 会静默忽略）
mask-image: url() 在 Safari 中路径正确却仍不加载？
即使路径看起来没有问题，Safari 对 url() 的解析依然非常严格。比如空格、未编码的 #、换行符、file:// 协议以及 CORS 跨域限制，都会让 mask-image 直接失效，而且通常没有明显报错。此时在 DevTools 的 “Computed” 面板中，你会看到 mask-image 被解析成 none。
在移动端这个问题更常见，尤其是 iOS Safari。只要 URL 中带有特殊字符且未正确编码，浏览器可能直接拒绝解析，图标或遮罩效果像是“突然消失”，甚至连 network 请求都不会发出。
- 优先使用 base64 内联 SVG：
mask-image: url("data:image/svg+xml,%3Csvg...%3E"); - 避免使用
file://协议测试，建议改成本地 server（如python3 -m http.server） - URL 里的
#必须编码成%23，空格必须写成%20 - 确认服务器返回正确的 MIME 类型（
image/svg+xml或image/png）
写了 mask-image 却看到全黑/全透明/什么都没有？
这并不只是 Safari 的问题，而是 CSS 遮罩在各大浏览器中的通用机制。mask-image 不是普通贴图，它读取的是遮罩资源的亮度（luminance）或 alpha 通道，从而决定目标元素哪些区域可见。一般来说，白色显示、黑色隐藏、灰色半透明，但前提是被遮罩的元素本身必须先有可显示内容。
很多情况下的“失效”其实是这样发生的：mask-image 已经生效 → 目标元素没有背景或内容 → 被遮罩后看起来只剩透明 → 最终视觉效果就像元素消失了一样。
- 给目标元素添加
background-color或background-image（即使只是background: #000也可以） - 如果目标是
overflow: hidden裁切 - 检查父元素是否使用了
transform或will-change，避免触发异常合成层问题 - 通过 DevTools 的 “Computed” 面板确认
mask-image最终是否被解析为有效值，而不是none
渐变遮罩 linear-gradient() 在 Safari 中表现诡异？
Safari 对渐变遮罩的解析规则比较特殊，通常要求渐变颜色尽量使用纯灰阶，例如 #000、#888、#fff。如果使用 transparent 或 rgba()，它可能会被转换为 #000，或者直接触发降级，结果就容易出现全黑、全显或显示异常的问题。
而在 Firefox 中情况更严格：目前它仍会完全忽略 mask-image: linear-gradient()，即使语法正确，声明存在也可能等于无效。
- 不要使用
transparent，改用#000（隐藏）或#fff（显示） - 尽量避免
rgba(0,0,0,0)，Safari 对这种写法的解析并不稳定 - 如果要兼顾跨浏览器兼容性，更稳妥的方案是改用内联 SVG 作为
mask-image: url(#myMask)，并在 SVG 中定义 - 如果必须使用渐变，建议显式添加
mask-mode: luminance，并只使用十六进制灰阶颜色
还有一个很容易被忽略的关键点：Safari 对 mask-image 的处理更接近“要么全部生效，要么完全失效”。它不会部分支持，不会给出 warning，也不会自动回退到默认行为。只要路径、前缀、颜色、元素内容等任一环节出错，最终结果往往就是页面内容彻底不可见，而排查时你可能还误以为只是普通 CSS 写法问题。
