mask-image: url() 无效因浏览器默认平铺且缩放不可控，须显式声明 mask-size、mask-repeat、mask-position；safari 必须加 -webkit-mask-image 前缀；蒙版图需灰度/alpha 通道，png 优于 webp，不可直接作用于 img 标签。
mask-image: url() 为什么没反应
直接写 mask-image: url(mask.png) 几乎必然失效——不是路径错了，也不是 CSS 没加载，而是浏览器默认把蒙版图当“小图标”平铺（mask-repeat: repeat），且缩放行为不可控（mask-size: auto 在各浏览器中结果不一致）。最终效果：要么看不见，要么满屏密密麻麻的重复蒙版块。
必须显式声明以下三项，缺一不可：
-
mask-size：推荐cover、contain或具体值如100% 100%；避免用auto -
mask-repeat：绝大多数场景必须写no-repeat -
mask-position：默认居中，但若容器宽高比与蒙版图不匹配，cover会裁边，此时可改用contain或手动调成top left
为什么 Safari 下 mask-image 完全不生效
因为 Safari（包括 iOS 和 macOS 当前所有版本）仍强制要求 -webkit-mask-image 前缀。只写标准 mask-image 等于没写。
正确写法必须双写：
div {
-webkit-mask-image: url(mask.svg);
mask-image: url(mask.svg);
}
其他 mask-* 属性（如 mask-size、mask-position）无需加前缀，现代 Safari 已支持无前缀版本。但仅 mask-image 这一项，漏掉 -webkit- 就等于放弃整个 Safari 用户群。
mask-image 的灰度逻辑和图片准备要点
mask-image 不是“贴图”，而是 Alpha 裁切指令：它只读取源图的亮度或透明度通道，决定目标内容哪些区域可见。
关键规则：
- 纯白（
#fff或 alpha=1）→ 内容完全显示 - 纯黑（
#000或 alpha=0）→ 内容完全隐藏 - 灰色 → 按灰度值映射为对应透明度（非简单明暗，是 alpha 值）
- PNG 必须带有效 Alpha 通道：Photoshop 导出要勾选“透明度”，Figma 要选 “Include alpha”
- 别用 WebP 做蒙版图——旧 Safari 不识别其为合法遮罩源
别对 ![]()
标签直接加 mask-image
这是最常踩的坑：<img src="photo.jpg"> 上直接写 mask-image，实际作用的是 <img> 元素的盒模型（含 margin/border/padding），不是图像本身。而图像在盒内是 content，mask 不会穿透进去裁切。
正确做法是：
- 把图片设为容器的
background-image - 给该容器（如
<div>）应用 <code>mask-image - 确保容器有明确宽高（
height: auto在响应式场景下极易导致塌陷） - 若需响应式，优先用
mask-size: contain+mask-position: center+mask-repeat: no-repeat
真正起作用的从来不是“蒙版图多好看”，而是它是否被正确采样、缩放、定位，并叠加在有背景/内容的元素上。漏掉任意一个显式声明，都可能让遮罩在某个浏览器里彻底消失。
