CSS mask-image给图片添加复杂形状遮罩

mask-image 踩坑实录：三个最常见的“失效”原因

CSS 的 mask-image 看似简单，实际使用时却容易遇到三种典型问题：它只作用于 Alpha 通道，元素必须本身带有可见内容；PNG 遮罩图的导出设置会直接影响浏览器的解析结果；不同浏览器对 mask-image 的支持存在明显差异，Safari 要求灰阶渐变，Firefox 可能完全忽略 linear-gradient()。每个问题单独看都不复杂，但叠加在一起就容易让人困惑。

想通过 mask-image 给图片添加复杂形状遮罩，直接写一行代码往往不行——必须先解决“遮罩没效果”“形状不对”“Safari/Firefox 不显示”这三个高频卡点。

写了对 mask-image 却看不到遮罩效果，是什么原因？

根本原因在于 mask-image 不是用来显示颜色或图像内容，而是控制 Alpha 通道：白色保留（显示），黑色隐藏（透明），灰色则半透明。如果目标元素本身没有背景、没有内容、没有 background-color 或 background-image，那么遮罩后的结果就只剩透明区域，视觉上等于消失。

• 第一步确认目标元素拥有可见内容，例如使用 标签，或者为
  设置 background-image
• 不要把 mask-image 当作 background-image 的替代品，它本身不产生颜色，只控制透不透明
• 检查是否意外触发了 overflow: hidden 或父级裁剪，这可能会掩盖遮罩边缘

使用 mask-image: url() 加载 PNG 遮罩图时，为什么星形或三角形边缘发虚，甚至完全变黑？

关键在于 PNG 文件必须带有有效的 Alpha 通道，并且导出设置会直接影响浏览器的灰度解析。浏览器并不按照 RGB 颜色值渲染遮罩，而是提取亮度值（Luminance）作为 Alpha 权重：纯白（#fff）对应 100% 显示，纯黑（#000）对应 0% 显示。

• 在 Photoshop 中导出时务必勾选“透明度”，关闭“仿色”和“转换为 sRGB”，避免灰阶偏移
• Figma 导出应选择 “PNG (with alpha)”，不要选 “JPG” 或 “SVG without alpha”
• 通过 DevTools 的“Computed”面板检查 mask-image 是否成功加载；如果显示 none，说明路径错误或 CORS 策略拦截（注意 Safari 对 file:// 协议禁止使用外部 mask 图）

用 linear-gradient() 实现不规则渐变遮罩，为什么 Safari 和 Firefox 的表现截然不同？

这个问题不是语法写错，而是不同浏览器对渐变的“灰度解析标准”不统一。Safari 要求渐变颜色必须是纯灰阶（例如 #000、#333、#fff），Firefox 目前仍完全忽略 mask-image: linear-gradient() 声明。

• 安全写法：使用 mask-image: linear-gradient(to right, #000, #000 50%, #fff 50%, #fff) —— 全部采用十六进制灰阶，避免 transparent 或 rgba()
• Chrome/Edge 需要同时书写 -webkit-mask-image 才能生效（旧版本 Blink 内核强制要求加前缀）
• 真正跨浏览器兼容的做法：改用内联 SVG 作为 mask-image: url(#myMask)，在 SVG 中定义 和 ，彻底避开渐变解析分歧

想让遮罩跟随鼠标移动或实现响应式缩放，为什么 mask-position 和 mask-size 无法动态变化？

需要警惕的是：mask-position 和 mask-size 在 Firefox 中至今不可动画，Safari 的动画支持也极不稳定，直接添加 transition 基本无效。

• 替代方案：利用 background-position 模拟位移——让 mask-image 和 background-image 使用相同的渐变结构，仅通过 background-position 错开，再对 background-position 添加 transition
• 必须配合 mask-repeat: no-repeat; mask-size: 100% 100%，否则位移会被重复或拉伸干扰
• 响应式缩放建议改用 clip-path: polygon() + CSS 变量传递坐标，比 mask-image 更易控制（但要注意 Firefox 对变量坐标偶发解析失败的问题）

综合来看，使用 mask-image 的真正难点不在于写对一行代码，而在于根据形状精度、动态需求和目标浏览器基线，判断该选用 PNG、SVG 还是渐变方案。形状越复杂，越早切换到 SVG 方案，踩坑就越少。