mask-image 渐变遮罩需按浏览器差异处理：safari 仅支持 luminance 模式，须用 #000/#fff；firefox 不支持渐变，必须 fallback 到 url 编码的内联 svg；chrome/edge 需双写 -webkit-mask-image 和 mask-image；图片遮罩需用 background-image + 固定尺寸容器；文字遮罩需结合 background-clip: text 与透明色。
直接结论：用 mask-image 做透明渐变遮罩，不是写个 linear-gradient() 就完事——它在 Safari 里会静默失效，在 Firefox 里压根不认，Chrome/Edge 还得靠 -webkit-mask-image 才动起来。
mask-image 渐变不生效？先查浏览器支持和颜色写法
常见错误现象：mask-image: linear-gradient(to right, black, transparent) 在 Safari 里整个元素全显，在 Firefox 里完全没反应，Chrome 也可能黑屏或白屏。
- Safari（iOS 15.4+ / macOS Monterey 后）只认 luminance（亮度值），
transparent不是有效灰度色，会被强制转成#000（全显），必须改用#000（可见）和#fff（隐藏） - Firefox 截至 2026 年中仍不支持任何渐变值作为
mask-image，声明会被直接忽略，必须 fallback 到 SVG 方案 - 别用
black/white别名——Safari 对别名解析不稳定，#000和#fff才真正可靠
图片渐变淡出必须用 background-image + 容器尺寸控制
对 <img> 标签直接加 mask-image 几乎一定失败：遮罩作用于整个盒模型（含 padding/border），而响应式图片的 height 是 auto，容器无明确尺寸时 mask 区域常塌陷为 0×0。
- 正确做法：把图片设为父容器的
background-image，再对容器应用mask-image - 容器必须有可计算尺寸——要么写死
width和height，要么用aspect-ratio（现代浏览器支持良好） - 示例：
.fade-container { width: 300px; aspect-ratio: 4/3; background-image: url("photo.jpg"); background-size: cover; -webkit-mask-image: linear-gradient(to bottom, #000, #fff); mask-image: linear-gradient(to bottom, #000, #fff); mask-size: 100% 100%; mask-repeat: no-repeat; }
文字渐变遮罩要绕过 color 直接作用域限制
mask-image 默认不作用于纯文字（color），只裁剪 background 和 border。想让文字本身“从左到右淡出”，得先把文字变成背景内容。
- 核心组合：
color: transparent+background-clip: text+-webkit-background-clip: text+ 背景渐变 - 遮罩本身仍需
-webkit-mask-image（Safari 必须）和mask-image（Chrome/Edge 需双写） - Safari 中渐变终点必须写
transparent（不能用rgba(0,0,0,0)），但起点要用#000或black，否则亮度解析异常 - 控制淡出范围靠
mask-size和mask-position：比如mask-size: 200% 100%+mask-position: -100% 0可实现滑入动画
Firefox 兼容只能靠内联 SVG，且格式不能错
当目标浏览器必须包含 Firefox 时，放弃 linear-gradient() 是唯一现实选择。SVG <mask></mask> 是目前最稳定 fallback。
- 必须用
url("data:image/svg+xml;utf8,...")写法，且所有特殊字符（, <code>>, 空格）要 URL 编码 -
<stop></stop>必须写stop-color="black"（不是fill，也不是省略），且结尾锚点#m不能漏 - 示例片段：
mask-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg'%3E%3Cmask id='m'%3E%3ClinearGradient y2='1'%3E%3Cstop offset='0' stop-color='black'/%3E%3Cstop offset='1' stop-color='white'/%3E%3C/linearGradient%3E%3C/mask%3E%3C/svg%3E#m"); - 注意：这个 SVG 只定义遮罩图案，文字或图片内容仍需通过
background或content提供
最易被忽略的一点：mask 是简写属性，单独写它会重置 mask-size、mask-repeat 等，默认行为可能让渐变平铺或缩放错位。永远优先拆开写 -webkit-mask-image、mask-image、mask-size、mask-repeat —— 稳定性比少敲几行代码重要得多。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
