优先用渐变而非SVG实现mask-image，因渐变轻量、可动画、易调试；仅不规则路径擦除才需SVG；配合mask-position与mask-size动画才能实现可控转场；注意兼容性需同时写mask-image和-webkit-mask-image。
mask-image 用渐变还是 SVG？选对才能省事
绝大多数转场效果，linear-gradient 或 radial-gradient 就够了；只有当你需要不规则路径擦除（比如沿着手绘轮廓、星形缺口、波浪边缘）时，才值得上 SVG。
渐变写法轻量、可动画、易调试；SVG 需额外定义 <defs> 和引用 ID，还要处理坐标缩放和 viewBox 对齐问题，稍有偏差就露白边或错位。
-
mask-image: linear-gradient(to right, #000 0%, #000 50%, transparent 50%, transparent 100%)是最常用水平擦除起点 - 想做“从中心扩散”，用
radial-gradient(circle at center, #000 0%, #000 30%, transparent 30%)，注意第二段透明起始点要和不透明段紧邻，否则中间会留白 - 避免直接写
rgba(0,0,0,0)当透明色——某些旧版 Safari 会把它当黑，改用transparent更稳
mask-position + mask-size 配合动画才可控
单纯设 mask-image 只能定格，真正实现“动起来”的转场，靠的是 mask-position 在 mask-size 扩展后的画布上滑动。
比如水平擦除：把遮罩宽度设成 200% 100%，初始位置设为 -100% 0，再用 transition 或 @keyframes 把它拉到 0 0，就能看到内容从左往右“揭开”。
立即学习“前端免费学习笔记（深入）”；
-
mask-size: 200% 100%表示遮罩图横向拉伸一倍，给动画留出空间 -
mask-position: -100% 0是让遮罩左边缘对齐元素左边缘，此时右边一半遮罩还在元素外，所以全黑/全透 - 动画终点设
mask-position: 0 0，即遮罩完全覆盖元素，显示全部内容 - 别忘了加
mask-repeat: no-repeat，否则重复平铺会破坏过渡逻辑
浏览器兼容性坑：-webkit-mask-image 还得留着
截至 2026 年中，Firefox 已原生支持 mask-image，但 Safari（尤其是 iOS 17 及更早）仍需 -webkit-mask-image 前缀，Chrome 则两者都认。漏掉前缀，Safari 下直接不生效。
不是所有渐变语法都兼容：Safari 对 image()、element() 和多层遮罩支持弱，优先用单层 linear-gradient 或 radial-gradient。
- 必须同时写两行：
mask-image: ...;和-webkit-mask-image: ...; - 避免在
mask-image中混用url()和渐变——部分 Android WebView 会忽略整条声明 - 测试时真机必跑：模拟器常误判 mask 渲染，尤其带
mask-mode: alpha的场景
边缘淡出不是 opacity，是 mask 的 alpha 渐变
很多人想让图片四边“淡出”，第一反应是套 opacity 或 box-shadow，但那是整体变灰/发虚；真正“边缘淡出”是指：中间清晰可见，越靠近边缘越透明，且背景能透过——这只能靠 mask-image 的 alpha 渐变实现。
关键不是调颜色，而是控制遮罩自身的透明度分布：用 linear-gradient 从 #000（完全遮挡）过渡到 transparent（完全透出），再反向拼接，形成上下左右四边衰减。
- 上边淡出：
linear-gradient(to bottom, transparent 0%, #000 20%) - 合成四边：用
mask-composite: exclude或叠加多个mask-image层（注意顺序） - 慎用
mask-mode: luminance——它把亮度当 alpha，深色图边缘可能意外变实 - 如果目标是 Google Maps 这类 iframe，需包裹一层
div容器再设 mask，iframe 自身不响应 mask
