mask-image 默认按亮度（luminance）模式解析图像，而非alpha通道，导致PNG透明背景被当全黑、transparent渐变失效、Firefox兼容性差等静默问题。
mask-image 为什么让内容“全黑”或“全白”——遮罩图 alpha 通道被误读
设置 mask-image 后元素突然变黑、变透明，甚至完全消失，大概率不是 CSS 写错了，而是浏览器把你的遮罩图当成了「全黑」或「全白」来解析。根本原因在于：CSS 遮罩默认按 luminance（亮度）模式解释图像，而非 alpha（透明度）通道——哪怕你用的是带 alpha 的 PNG，它也不会直接读取透明度值。
常见错误现象：
- 用 Photoshop 导出的带透明背景 PNG 作为遮罩，结果整个元素不可见（浏览器把它当全黑处理）
- SVG 遮罩里用了
fill="none"或没设fill，Firefox 下直接全黑 -
mask-image: url("mask.png")在 Chrome 有反应，Firefox 完全没效果
实操建议：
- 遮罩图必须明确区分「显示区」和「隐藏区」：纯白（
#fff）= 完全显示，纯黑（#000）= 完全隐藏，灰度 = 半透；别依赖 PNG 的 alpha 层做逻辑判断 - 若坚持用 PNG，导出时务必关闭「透明背景」，改用白色底 + 黑色镂空区域（即「黑白图」），并确认保存为非压缩格式（如 PNG-24 无抖动）
- SVG 遮罩内必须显式声明
fill="white"或fill="black"，不能留空或用fill="none"—— Firefox 对此极其严格 - 想强制走 alpha 通道？加
mask-mode: alpha，但注意：此时linear-gradient(black, transparent)依然无效，因为transparent不是 alpha 渐变，得换rgba(0,0,0,1)→rgba(0,0,0,0)
mask-image: linear-gradient() 为啥渐变失效——颜色语义和模式错配
写 mask-image: linear-gradient(to right, black, transparent) 却没淡出效果？问题不在语法，而在浏览器根本没按你想的方式读这张“渐变图”。transparent 在 luminance 模式下等价于黑色（亮度为 0），于是整条渐变被当成「黑→黑」，结果就是全遮盖。
立即学习“前端免费学习笔记（深入）”；
实操建议：
- 一律用明确的 RGB/HSL/十六进制色值：
mask-image: linear-gradient(to right, #fff, #000)，确保起始白、结束黑 - 避免
transparent和rgba()，尤其在luminance模式（默认）下，它们会被转成纯黑，不是“透明” - 如果真要基于 alpha 控制，必须同时写：
mask-image: linear-gradient(to right, rgba(0,0,0,1), rgba(0,0,0,0))+mask-mode: alpha - Safari 对
rgba()渐变支持不稳定，生产环境优先用#fff/#000+mask-mode: luminance
mask-image 失效却不报错——三类静默失败场景
mask-image 最难调试的地方是：它不加载、不渲染、不报错，只默默回退到 none。控制台一片安静，开发者工具里也看不出异常。
实操建议，按顺序排查这三件事：
- 检查图片是否真正加载成功：打开 DevTools → Network → Filter “Img”，找你的 mask 图 URL，看状态码是不是 200；404 或 CORS 跨域失败时，
mask-image直接失效，且无提示 - 确认元素本身有「可绘制内容」：空
<div></div>、display: none、父级overflow: hidden且子元素溢出被裁，都会导致蒙版无处生效 - 验证 Firefox 兼容性：它至今不支持
mask-image的标准语法，必须靠-webkit-mask-image前缀兜底；但更关键的是，Firefox 会忽略未声明mask-mode或mask-size的规则，哪怕写了前缀
mask-image 与 clip-path 混用时内容突然消失——执行顺序陷阱
当你同时写了 clip-path 和 mask-image，却发现元素不见了，不是代码冲突，而是浏览器严格执行了渲染管线顺序：先 clip-path 几何裁剪，再对裁剪后的结果应用 mask-image。如果 clip-path 把内容全切掉了，mask-image 就没东西可蒙。
实操建议：
- 调试时临时注释掉
clip-path，确认mask-image单独是否生效 - 若必须混用，确保
clip-path保留足够区域（比如用inset(0)或略缩放的circle()），给mask-image留出操作空间 - 不要指望
mask-image能“扩大”可见区域——它只做减法，不能补回被clip-path切掉的部分 - 动画中尤其危险：
transform+mask-image在 Safari 下常因定位偏移导致擦除错位，建议把transform提到父容器，保持 mask 坐标系稳定
最易被忽略的一点：mask-image 的生效前提是「浏览器认为该元素值得绘制」。哪怕所有 CSS 都写对了，只要它被父级 visibility: hidden、opacity: 0 或 CSS containment（如 contain: layout paint）意外拦截，蒙版就彻底静音。这种失效不会出现在任何面板里，只能靠逐层移除父级样式来定位。
