mask-image裁剪失效主因有三：SVG遮罩未设width/height或maskUnits导致坐标系错乱；误将黑白语义颠倒（黑=透明，白=显示）；PNG未用灰度图而依赖alpha通道。
mask-image 裁剪失效的常见原因
直接写 mask-image: url(mask.svg) 却没效果，大概率是 mask 图像本身没生效——SVG mask 默认需要 maskUnits="userSpaceOnUse" 且内部 <mask> 必须有明确尺寸（比如 width="100%" height="100%"），否则浏览器按默认 objectBoundingBox 解析，坐标系缩放后常导致全黑或全透。
另一个高频坑：mask 图像中黑色区域表示“透明”，白色表示“显示”，灰度值决定透明度。很多人误以为黑=显示、白=隐藏，结果裁出来全是反的。
- 确保 mask SVG 文件内
<mask>标签显式声明width和height（推荐用100%） - 检查 mask 内容是否为纯黑/白填充，避免意外描边或半透明填充
- 若用 PNG 作 mask，必须是灰度图；带 alpha 的 PNG 不会按 alpha 当 mask，只看亮度值
用 CSS 渐变生成简单 mask（不用外部文件）
想快速实现圆角切角、菱形、三角形等基础不规则形状，没必要引入 SVG 文件。mask-image 支持 linear-gradient 和 radial-gradient，直接写在 CSS 里更轻量、可维护。
例如裁成菱形：
立即学习“前端免费学习笔记（深入）”；
img {
mask-image: linear-gradient(45deg, black 50%, transparent 50%),
linear-gradient(-45deg, black 50%, transparent 50%),
linear-gradient(45deg, transparent 50%, black 50%),
linear-gradient(-45deg, transparent 50%, black 50%);
mask-size: 100px 100px;
mask-repeat: no-repeat;
mask-position: center;
}
关键点：
- 多个渐变叠加时，顺序影响最终遮罩——后写的层覆盖前一层
-
mask-size必须设，否则渐变默认铺满整个元素，菱形就看不见了 - Chrome 和 Safari 对多层渐变 mask 支持良好，Firefox 需要加
-webkit-mask-image前缀（但现代版本已基本原生支持）
SVG mask 中 path 路径的坐标对齐问题
用 <path d="M...Z"> 定义复杂轮廓时，图片和 mask 的坐标系不匹配是最难调试的一环。mask SVG 里的 viewBox 和目标图片宽高不一致，会导致路径偏移或缩放失真。
稳妥做法：
- 让 mask SVG 的
viewBox与目标图片原始尺寸一致（如图片是 400×300，viewBox="0 0 400 300"） - 在 CSS 中用
mask-size: contain或cover控制缩放行为，比固定像素值更健壮 - 避免在 SVG 中用
transform移动 path——改用d属性重算坐标更可控 - 调试时临时给 mask 元素加背景色（
fill: red）并设opacity: 0.5，肉眼验证路径位置
mask-image 与 clip-path 的关键区别
别混淆 mask-image 和 clip-path：前者是基于像素明度的软裁剪（支持半透明过渡），后者是硬边几何裁剪（只有显/隐，无灰度）。如果只需要镂空一个星形或心形，clip-path: path("M...") 更简单；但要做羽化边缘、渐变遮罩、或复用已有 PNG/SVG 纹理，就必须用 mask-image。
兼容性上，mask-image 在 Safari 和 Chrome 稳定支持多年，Firefox 自 93+ 也已去掉前缀；而 clip-path 的 path() 函数在旧版 Safari 仍需 -webkit-clip-path。
真正容易被忽略的是：mask 是叠加在元素内容上的独立图层，它不改变元素盒模型尺寸，也不影响事件捕获区域——点击“被 mask 掉”的区域依然能触发 click，这点和 clip-path 行为一致，但和 overflow: hidden 不同。
