mask-image 渐变遮罩不生效的根本原因是它只作用于元素的绘制内容（background/border），若 background 未显式设置或为 transparent，则无内容可遮；需确保 background 存在、mask-mode 正确、safari 加 -webkit- 前缀、渐变终点用 transparent 而非 rgba(0,0,0,0)，并避免 css 变量直接用于 mask-image 渐变色。
mask-image 渐变遮罩不生效？检查 background 和 mask 的层叠关系
直接说结论：mask-image 只作用于元素的「绘制内容」，如果 background 没有显式设置（比如用了 background: transparent 或没设），遮罩可能看起来完全没反应——不是语法错，是它根本没东西可遮。
常见错误现象：写了 mask-image: linear-gradient(...)，但元素还是实色块，或者只边缘模糊一点，中间完全没渐变过渡。
-
mask-image默认只遮罩元素的background和border（不含文字、子元素），文字默认穿透遮罩；如需遮文字，得把文字转成background-image或用-webkit-text-fill-color: transparent+background-clip: text - 必须同时设
mask-mode: alpha（默认值）或mask-mode: luminance，否则某些浏览器（尤其是 Safari）会忽略渐变值 - Safari 对
mask-image的支持依赖-webkit-mask-image前缀，且仅支持linear-gradient，不支持radial-gradient或conic-gradient - 如果用
background: currentColor或变量色，确保mask-image的渐变色阶里有足够对比度（比如从black到transparent），否则遮罩灰度值太接近，效果微弱
用 mask-image 实现文字颜色渐变+遮罩镂空效果
想让文字像被“撕开”一样露出底图，又带颜色渐变？不能只靠 background: linear-gradient + background-clip: text，那只是填色；真正镂空要靠 mask-image 控制透明区域。
使用场景：标题页视觉焦点、卡片标签、响应式 banner 文字透底。
立即学习“前端免费学习笔记（深入）”；
- 先给文字容器设
background-image: url(...)或background: linear-gradient(...)作为底层 - 文字本身用
color: transparent+background-clip: text+-webkit-background-clip: text把背景“贴”到字形上 - 再加
-webkit-mask-image: linear-gradient(to right, black, transparent)（注意方向要和背景渐变一致） - 关键点：Safari 中必须用
-webkit-mask-image，且渐变终点必须是transparent（不能写rgba(0,0,0,0)，它不识别）
h1 {
background: linear-gradient(90deg, #3498db, #e74c3c);
-webkit-background-clip: text;
background-clip: text;
color: transparent;
-webkit-mask-image: linear-gradient(to right, black, transparent);
mask-image: linear-gradient(to right, black, transparent);
}
mask-image 配合 CSS 变量动态换色时的兼容性陷阱
想用 color 变量驱动遮罩颜色？不行。mask-image 不接受 CSS 变量作为渐变色 stops，也不能用 var(--mask-color) 直接插进 linear-gradient() 里——浏览器会当作无效值丢弃。
性能影响：每次改变量都触发重绘，但因为 mask-image 是位图级处理，频繁变更会导致 Safari 卡顿明显。
- 可行方案：用
@property注册自定义属性并设syntax: "<color>"</color>，再在mask-image中引用（仅 Chrome 115+ 支持） - 降级方案：用 JS 动态生成
style标签注入内联mask-image，或预设几套 class（如.mask-red,.mask-blue）切换 - 别踩坑：不要在
mask-image里混用hsl()和rgb()写法，旧版 Safari 对hsl()解析不稳定 - 注意单位：渐变角度写
90deg比to top兼容性更好，后者在部分 Edge 版本中失效
mask-image 在高 DPI 屏幕下边缘发虚？补一个 1px 黑边
MacBook 或 Windows 高分屏上，mask-image 渐变边缘常出现半透明毛边，尤其当遮罩用于裁剪图标或徽章时特别明显——这不是抗锯齿问题，是浏览器对亚像素 mask 渲染的精度丢失。
最容易被忽略的地方：这个现象在开发机上看不出来，一上真机或截图放大就暴露。
- 简单修复：在渐变末尾加一个 1px 的纯黑硬边，比如
linear-gradient(to right, black 0%, black 99%, transparent 100%) - 别用
mask-border替代，它和mask-image是两套机制，叠加后行为不可控 - 如果用
mask-composite: intersect多层遮罩，确保每层都加硬边，否则层间混合会放大模糊 - 测试时务必在实际设备上用 Safari 和 Chrome 并排对比，Firefox 对
mask-image的渲染逻辑和其他浏览器差异最大
