CSS变量不能嵌入mask-image函数参数，需将整个渐变声明存为变量；多层遮罩需DOM层级叠加而非同一元素重复设置；动画遮罩推荐用background-position模拟；响应式裁剪优先选mask-image配变量半径。
mask-image 里不能直接用 var() 填参数
浏览器会把 mask-image: linear-gradient(90deg, #000 var(--start), #000 var(--end)) 当作无效值丢弃，最终遮罩不生效——这不是 bug，是规范限制：CSS 变量不能嵌入函数参数内部。
真正能用的写法是把整个渐变声明存成变量：
-
--mask-grad: linear-gradient(90deg, #000 20%, #000 80%)（注意数值已计算好，别塞calc()） - 再在元素上写
mask-image: var(--mask-grad) - 变量必须定义在
:root或目标元素自身，确保作用域覆盖
Chrome 115+ / Safari 16.4+ 支持变量内联计算，Firefox 至今不认 var() 在 linear-gradient() 里的动态解析，别赌兼容性。
多层 mask 叠加时，z-index 不起作用
mask-image 是图像级遮罩，它只控制“当前元素内容是否可见”，不创建新图层；想叠加多个遮罩视觉效果，得靠 DOM 层级 + z-index + position: absolute 组合。
立即学习“前端免费学习笔记（深入）”；
正确结构：
- 父容器设
position: relative - 每个遮罩层用
position: absolute; top: 0; left: 0; width: 100%; height: 100% - 用
z-index控制谁在上（比如.mask-1 { z-index: 1 },.mask-2 { z-index: 2 }） - 每层可独立配
mask-image、background-color、backdrop-filter
别指望给同一个元素反复写 mask-image 实现叠加——后写的会覆盖前写的，不是叠加。
想让遮罩“动起来”，别碰 mask-position
mask-position 在 Firefox 中至今不可动画，Chrome/Safari 虽然标为 animatable，但实际表现滞后、卡顿明显。硬上 @keyframes 或 transition 基本等于白忙。
绕过方案：用 background-position 模拟位移
- 让
mask-image和background-image使用同构渐变（方向、色停一致） - 设
mask-repeat: no-repeat; mask-size: 100% 100% - 对
background-position: var(--mask-x) center做动画，视觉上就是遮罩在滑动 - 例如：
--mask-x: -50%→ 遮罩向左偏移一半宽度
这个 trick 依赖背景与遮罩几何一致，错一点就露底，调试时建议先关掉 mask-repeat 看对齐效果。
clip-path 变量坐标 vs mask-image 渐变：响应式裁剪选哪个？
如果目标是动态调整裁剪形状（比如圆角随屏幕缩放变化），clip-path: polygon(var(--p1), var(--p2)) 看似灵活，但 Firefox 对变量坐标的解析仍不稳定，Chrome 120+/Safari 17+ 才算靠谱。
更稳的选择是 mask-image: radial-gradient() 配合 CSS 变量控制半径和位置：
-
--mask-radius: 60px→mask-image: radial-gradient(circle at center, #000 0%, #000 var(--mask-radius), transparent var(--mask-radius)) - 变量可绑定视口单位（
vw/vh），天然响应式 - 比
clip-path更容易做缓动动画（改mask-size或mask-position即可）
真要用 clip-path 变量，务必加降级：fallback 到固定值或媒体查询断点，别裸奔。
