mask-image 失效主因是三方面：需检查图片加载与cors、元素必须有可绘制内容、firefox要求svg mask内fill明确；渐变蒙版须用luminance模式并避免rgba；clip-path优先于mask-image执行。
mask-image 设置后没效果？先检查这三件事
绝大多数 mask-image 失效不是语法写错，而是被浏览器默认行为“静音”了。它必须配合 mask-mode、mask-repeat 和元素自身渲染状态一起生效。
-
mask-image默认值是none，但即使设了url(...)，若图片加载失败或跨域未配CORS，控制台不报错，只默默回退到none - 元素必须有「可绘制内容」：空
div、display: none、或父级overflow: hidden且裁剪过界，都会让蒙版不可见 - Firefox 对
mask-image的 SVG<mask></mask>支持更严格，需确保<mask></mask>内部有明确fill（如fill="white"），否则全黑
用渐变做 mask-image 时，alpha 通道不起作用？
很多人以为 mask-image: linear-gradient(black, transparent) 能实现淡出，结果发现边缘生硬——因为 CSS 渐变本身不带 alpha，transparent 在 mask 中等价于 rgba(0,0,0,0)，而 mask 解析的是 luminance（亮度值），不是 alpha。
- 正确写法是用
mask-image: linear-gradient(to right, black, transparent)，但必须搭配mask-mode: luminance（默认值）才能按灰度解释；若设成mask-mode: alpha，则只有真正带 alpha 的图片或rgba()渐变才有效 -
rgba(0,0,0,0)在 luminance 模式下会被转成黑色（luminance = 0），导致“完全遮盖”，而不是“完全透出”——所以别用rgba()写渐变蒙版 - 想精确控制透明度过渡，推荐用内联 SVG：
mask-image: url("data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg"><mask id="m"><lineargradient y2="1"><stop offset="0" stop-color="white"></stop><stop offset="1" stop-color="black"></stop></lineargradient></mask></svg>#m")
mask-image 与 clip-path 混用时的层级陷阱
mask-image 和 clip-path 都能裁切内容，但它们作用阶段不同：clip-path 是几何裁剪（rendering pipeline 前期），mask-image 是像素级合成（后期），混用时顺序和叠加逻辑容易翻车。
- 两者同时存在时，浏览器先执行
clip-path，再对裁剪后的区域应用mask-image；如果clip-path把内容全裁掉了，mask 就没东西可蒙 -
mask-image不会扩大渲染区域——哪怕你用大尺寸 SVG mask，超出元素盒模型的部分仍被自动截断，不会像clip-path那样允许“溢出可见” - 动画中慎用
mask-image+transform：Safari 对 transform 后的 mask 定位常有偏移，建议把transform提到父容器，保持 mask 元素静态
SVG mask 引用外部文件时的路径与缓存问题
用 mask-image: url("/mask.svg#myMask") 是常见做法，但路径解析和缓存策略会让它在开发和上线环境表现不一致。
立即学习“前端免费学习笔记（深入）”；
- URL 中的 fragment（
#myMask）必须指向 SVG 文件内真实存在的id，且该<mask></mask>元素不能在<defs></defs>外层直接写——否则 Chrome 可能忽略 - SVG 文件被 HTTP 缓存后，改了里面
<mask></mask>内容但没改文件名，浏览器不会重新拉取，mask 表现就“卡住”了；建议加版本参数：url("/mask.svg?v=2#myMask") - 本地 file:// 协议下，大多数浏览器禁止跨文件引用 fragment，调试时务必起一个本地服务（如
npx serve），否则mask-image直接降级为none
mask-image，而是得时刻想着：它依赖什么、被谁裁过、在哪个坐标系里算、以及现在到底有没有真正在工作。 
