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 方案，从而减少踩坑。
