mask-image 是控制元素可见区域的蒙版属性，不替代 background-image；它仅通过 Alpha 或亮度决定显示/透明区域，需配合背景或内容才可见，支持 url()、渐变等源，灰度逻辑为白显黑隐，Safari 对 CORS 和 file:// 限制严格。
mask-image 不是 background-image 的替代品
很多人一上来就用 mask-image 替换 background-image，结果发现元素“不见了”——因为 mask-image 默认作用于整个元素的**Alpha通道**，不自带颜色或背景，它只控制“哪里显示、哪里透明”。必须配合 background-color、background-image 或内容本身才能看出效果。
- 没设
background时，mask 后只剩透明区域，视觉上等于消失 -
mask-image的值为none（默认）时，等效于无遮罩，但不等于“显示全部”——它仍受父级overflow和自身opacity影响 - 推荐写法：先确保元素有可见内容或背景，再叠加 mask
mask-image 支持的图像源类型和常见陷阱
mask-image 接收 url()、linear-gradient()、radial-gradient() 或 conic-gradient()，但关键在**灰度解释逻辑**：纯白（#fff / alpha=1）区域显示内容，纯黑（#000 / alpha=0）区域完全隐藏，灰色则按透明度比例混合。
- 使用 PNG 时，务必确认 Alpha 通道有效；Photoshop 导出需勾选“透明度”，Figma 导出要选 “Include alpha”
- 用 CSS 渐变做 mask 时，
linear-gradient(to right, black, white)是从左黑到右白 → 左侧被遮住、右侧显示，容易和直觉相反 - Safari 对
mask-image: url(...)的 CORS 要求更严格，本地文件协议（file://）下常静默失败，建议用本地服务器预览
mask-mode 和 mask-repeat 如何影响图形遮罩选择器行为
当你用一张小图案（如 SVG <circle></circle>）做遮罩，mask-mode 和 mask-repeat 决定它怎么铺排。默认 mask-mode: match-source 会缩放 mask 图像以匹配元素尺寸，而 mask-repeat: no-repeat 是默认值——这意味着你可能只看到遮罩的左上角一小块。
- 想平铺遮罩图案：设
mask-repeat: repeat，同时注意mask-size（例如mask-size: 20px 20px）控制单个单元大小 - 想保持 SVG 遮罩原始宽高比并居中：用
mask-mode: fixed+mask-position: center+mask-size: contain -
mask-mode: luminance在 Safari 中支持不稳定，生产环境慎用；Chrome/Firefox 将亮度转为 Alpha，但对纯色图无意义
mask-type: alpha vs luminance 的实际区别在哪
mask-type 决定浏览器如何从 mask 图像提取遮罩信息：alpha（默认）读取图像的 Alpha 通道，luminance 则把 RGB 转为灰度后当 Alpha 用。多数时候你根本不需要改它——除非你用的是不含 Alpha 的 JPG 或纯色 PNG。
立即学习“前端免费学习笔记（深入）”；
- JPG 做 mask 时，
mask-type: luminance才能生效；否则 JPG 全部当不透明（alpha=1），遮罩失效 - SVG 作为
mask-image时，其内部<mask></mask>元素已定义遮罩逻辑，mask-type不起作用 - 调试技巧：临时加
mask-border: 1px solid red（虽不标准但部分浏览器可辅助定位 mask 区域）
真正卡住人的往往不是语法，而是 mask 图像的隐式尺寸计算、渐变方向与遮罩方向的反直觉映射，以及 Safari 对内联 SVG mask 的解析差异——建议始终用 DevTools 的 Rendering 面板开启“Mask overlays”，实时看遮罩生效范围。
