直接用mask-image给图片加不规则遮罩失败主因是浏览器解析差异：safari要求灰阶色值、firefox忽略渐变、png导出未关仿色会导致边缘发虚或全黑；必须确保元素有可见内容、路径正确、无父级裁剪，且优先采用内联svg方案。
直接用 mask-image 给图片加不规则遮罩，90% 的失败不是写法错，而是没过浏览器解析关——Safari 要灰阶、Firefox 忽略渐变、PNG 遮罩图导出错一个选项就边缘发虚或全黑。
为什么写了 mask-image 却完全没效果
这不是“属性没生效”，而是浏览器压根没渲染出可被遮罩的内容。常见原因有三个：
-
img标签本身没问题，但父容器或自身没设置background-color或background-image——mask-image只控制 Alpha 通道，不提供内容；空盒子+遮罩=全透明，视觉上等于消失 - 写了
mask-image: url("star.png")，但路径 404 或跨域（尤其 Safari 对file://协议禁用外部 mask 图），DevTools 的 Computed 面板里显示值为none - 父级设置了
overflow: hidden或有裁剪上下文（如transform触发的层叠上下文），把遮罩边缘切掉了
mask-image: url() 加 PNG 遮罩图时边缘发虚或形状不对
PNG 不是“画什么就遮什么”，浏览器提取的是亮度值（Luminance）作为 Alpha 权重：纯白 #fff = 100% 显，纯黑 #000 = 0% 显，灰阶决定半透程度。导出设置直接影响结果：
- Photoshop 导出必须勾选“透明度”，关闭“仿色”和“转换为 sRGB”——否则灰阶偏移，星形尖角变糊或整块变黑
- Figma 导出选 “PNG (with alpha)”，别选 JPG 或 “SVG without alpha”
- 用 DevTools 检查该 PNG 在“Network”里是否加载成功，右键“Open in new tab”确认 Alpha 通道可见（背景应为棋盘格，不是白底）
mask-image: linear-gradient() 在 Safari/Firefox 中表现不一致
这不是兼容性补丁能解决的问题，是浏览器对渐变值的解析逻辑根本不同：
- Safari（15.4+）只认纯灰阶色：
#000、#333、#fff；transparent会被静默转成#000，rgba(0,0,0,0.5)直接降级为全透明 - Firefox（2026 年中）仍完全忽略
mask-image: linear-gradient()声明，等同于没写 - Chrome/Edge 支持良好，但旧版 Blink 内核需同时声明
-webkit-mask-image才触发渲染 - 别用
to bottom, black, transparent这类写法——在 Safari 中transparent→#000→ 全显；在 Firefox 中整条声明被跳过
真正跨浏览器稳定的方案：内联 SVG 遮罩
用 mask-image: url("data:image/svg+xml,...") 是目前唯一能在 Safari、Firefox、Chrome/Edge 上行为一致的方式，但必须满足四个硬性条件：
- SVG 必须 base64 编码或 URL 编码后塞进
url("data:image/svg+xml,")，不能直接写<svg></svg>标签 -
<path></path>必须闭合（以Z结尾），且fill="white"——mask-image把白色区域当“可见”，黑色/透明当“隐藏” -
viewBox宽高需与目标元素尺寸比例匹配；例如波浪边框，viewBox="0 0 300 10"表示路径高度只占容器的 1/30，避免拉伸变形 - 必须同时声明
-webkit-mask-image和mask-image，值完全一致；Safari 16.4+ 虽支持标准属性，但部分 SVG 渲染仍依赖前缀
最容易被忽略的一点：所有浏览器都按 alpha 通道解析 SVG，但只有 fill="white" 的路径才参与遮罩计算——哪怕你加了渐变或滤镜，最终起作用的仍是 white 区域的 alpha 值。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
