SVG路径作mask-image需URL编码整个字符串、显式设宽高、禁用ID引用，且mask-mode应统一设为luminance以确保黑白灰值按亮度解析，避免静默失效。
mask-image 设置为 SVG 路径时为什么没效果？
直接写 mask-image: url("data:image/svg+xml;utf8,<svg>...")</svg> 很容易失败，核心原因是 SVG 内容必须经过 URL 编码，且 <svg></svg> 标签里不能含换行、空格或未转义的 &、、<code>>。浏览器解析失败就静默降级为无遮罩。
实操建议：
- 用
encodeURIComponent()包裹整个 SVG 字符串（注意：不是只编码 path 部分） - SVG 必须声明
width和height，推荐设为100% 100%或具体像素值，否则渲染尺寸不可控 - 内部
<path></path>的d属性值无需额外编码，但整个字符串传入encodeURIComponent时会自动处理 - 避免在 data URL 中使用
id引用（如fill="url(#grad)"），外部引用在内联 SVG 中不生效
mask-image + mask-mode: alpha 和 luminance 的区别在哪？
mask-image 本身只提供“遮罩源图像”，真正决定哪些区域透明、哪些不透明的是 mask-mode。默认是 alpha，即取源图的 alpha 通道；若设为 luminance，则把源图的亮度（Y 通道）当透明度用——这对纯色 SVG 遮罩几乎没影响，但对 PNG/渐变等灰度敏感的遮罩图很关键。
常见误用场景：
立即学习“前端免费学习笔记（深入）”；
- 用黑色
<path></path>在白色背景 SVG 中做遮罩，却没设mask-mode: luminance→ 黑色 alpha=0，结果是“全透”，而非“只留路径形状” - 想实现文字镂空效果，用了白色文字 SVG，但没配
mask-mode: luminance→ 白色 alpha=1，反而全遮住 - 实际建议统一显式写
mask-mode: luminance，尤其当遮罩图含黑白灰时，行为更可预测
mask-image 使用 CSS 渐变时怎么控制方向和大小？
mask-image 支持 linear-gradient() 和 radial-gradient()，但它的尺寸默认按被遮罩元素自身宽高拉伸，不像背景图能用 mask-size 独立控制。
关键控制点：
-
mask-size对渐变有效，例如mask-size: 200% 200%可让线性渐变从左到右覆盖两倍宽度 -
mask-position移动渐变起点，比如mask-position: center top把径向渐变中心锚定在顶部中央 - 避免只写
mask-image: linear-gradient(to right, black, transparent)就完事——没mask-size时，渐变会压缩成 1px 宽条，几乎看不到过渡 - 若要响应式渐变遮罩，优先用
mask-size: cover或contain，比固定像素更健壮
mask-image 在 Safari 上不生效的常见原因
Safari（尤其 iOS 15.4 之前）对 mask-image 支持较保守，不报错但静默失效很常见。最常被忽略的是前缀和组合属性缺失。
保底写法必须包含：
-
-webkit-mask-image前缀，且值与标准mask-image完全一致 -
-webkit-mask-repeat: no-repeat（Safari 默认 repeat，会破坏遮罩逻辑） -
-webkit-mask-size: 100% 100%或具体值，不依赖默认 - 不要混用
mask复合属性和单个mask-image，Safari 解析不稳定
另外，Safari 不支持 mask-image 的 image-set() 或部分 SVG 滤镜，有兼容需求时优先用 base64 编码的精简 SVG。
