mask-image 无法生效的三大原因：一是仅控制 Alpha 通道，需确保元素有可见内容；二是 PNG 遮罩图必须含正确 Alpha 通道且导出禁用仿色与 sRGB 转换；三是浏览器兼容差异大，Safari 要求灰阶渐变、Firefox 忽略 linear-gradient，推荐改用内联 SVG 方案。
直接用 mask-image 给图片加复杂形状遮罩，行不通——除非你先解决“遮罩没效果”“形状不对”“Safari/Firefox不显示”这三个高频卡点。
为什么写了 mask-image 却看不到遮罩？
因为 mask-image 不是“贴图”，它只控制 Alpha 通道：白显、黑隐、灰半透。如果元素本身没背景、没内容、没 background-color 或 background-image，那遮罩后只剩透明区域，视觉上等于消失。
- 必须确保目标元素有可见内容（比如
<img>标签，或设置了background-image的<div>） - 别把
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>和<path>，绕过渐变解析分歧
想让遮罩随鼠标移动或响应式缩放，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 方案，越少踩坑。
