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

mask-image 踩坑实录：三个最常见失效原因全解析

关于 CSS mask-image 失效的问题，实际开发中有三个高频踩坑点：第一，它仅控制 Alpha 通道，元素本身必须具备可见内容；第二，PNG 遮罩图的导出设置直接影响解析结果；第三，浏览器兼容性差异明显，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 错开，再对其添加 transition
• 必须配合 mask-repeat: no-repeat; mask-size: 100% 100%，否则位移会被重复或拉伸干扰
• 响应式缩放建议使用 clip-path: polygon() + CSS 变量传递坐标，比 mask-image 更可控（但需注意 Firefox 对变量坐标的偶发解析失败）

纵观这些痛点，真正的难点不在于写对一行 mask-image，而在于判断该使用 PNG、SVG 还是渐变——这取决于你所需的形状精度、动态需求以及目标浏览器基线。形状越复杂，越应尽早切换到 SVG 方案，从而减少踩坑。