mask-image 不起作用最常见原因是未同时设置 mask-mode 和 mask-size，导致默认渲染异常；必须显式声明 mask-mode: luminance 才能使灰度渐变生效，且 mask-size 需设为 cover 或 100% 100% 避免裁剪。
mask-image 为什么不起作用？
最常见原因是没配 mask-image 的同时漏掉 mask-mode 或 mask-size，导致浏览器按默认值渲染成全透明或全不透明。CSS mask 默认是「alpha 遮罩」——它只认图片的 alpha 通道或渐变的透明度，**纯色渐变（比如 linear-gradient(black, white)）在部分浏览器里会被当作文本内容处理，直接失效**。
- 必须显式写
mask-mode: luminance才能让灰度值参与遮罩（黑=透明，白=不透明） -
mask-size: cover或100% 100%很关键，否则遮罩图可能被缩放裁剪，只盖住左上角一小块 - 别用
background-color直接叠在 mask 元素上——遮罩层和颜色层要分两层：一层设mask-image，另一层用伪元素或子元素填色
用纯 CSS 实现颜色块遮罩的最小可行写法
核心思路是：用一个元素做遮罩容器，再用伪元素塞进你要的颜色块，靠 mask-image 控制它的显示区域。不是“给颜色加遮罩”，而是“让颜色只在遮罩形状里出现”。
div.color-mask {
position: relative;
width: 200px;
height: 200px;
}
div.color-mask::before {
content: "";
position: absolute;
inset: 0;
background-color: #ff6b6b;
-webkit-mask-image: radial-gradient(circle at 50% 50%, black 0%, transparent 70%);
mask-image: radial-gradient(circle at 50% 50%, black 0%, transparent 70%);
-webkit-mask-mode: luminance;
mask-mode: luminance;
-webkit-mask-size: cover;
mask-size: cover;
}
注意：radial-gradient 里用 black 开头才能让中心不透明（luminance 模式下黑=不透明），别写成 white。
mask-image 在 Safari 和 Chrome 行为不一致？
是的。Safari（macOS/iOS）对 mask-mode: luminance 支持更严格，Chrome 有时会把没声明 mask-mode 的情况“自动猜”成 luminance，但一升级就翻车。另外，mask-image 不支持 CSS 变量动态替换路径或渐变值，想换遮罩形状就得换类名或 JS 操作 style.maskImage。
立即学习“前端免费学习笔记（深入）”；
- Safari 必须写
-webkit-mask-image+mask-image双声明，只写后者会完全失效 - 渐变里的单位（如
70%）不能省略，写70会被忽略 - 不要对
mask-image做transition——大多数浏览器不支持过渡遮罩图本身，只能过渡mask-position或mask-size
替代方案：什么时候该放弃 mask-image 改用 clip-path？
如果你只需要简单几何形状（圆形、多边形、椭圆），clip-path 更轻量、兼容性更好（连 IE 都支持基础版本），而且不用操心 luminance/alpha 模式切换。但 clip-path 是硬裁剪，没法做羽化、渐变边缘或图像纹理遮罩。
- 纯色圆角遮罩 → 用
clip-path: round(12px) - 需要边缘模糊 → 还得回到
mask-image+blur()滤镜组合（但注意性能） - 要兼容 iOS 14.5 以下 →
clip-path的path()语法不支持，只能用circle()/polygon()
mask-image 真正不可替代的地方，是当你需要一张 PNG 当遮罩图、或者用复杂渐变控制半透明过渡时——这时候，luminance 模式和 mask-size 的配合细节，就是最容易出问题的点。
