直接给加mask-image无效，因其作用于盒模型而非图像内容；必须将图片设为有明确宽高的容器的background-image，否则遮罩区域可能塌陷为0×0。
直接给 <img> 加 mask-image 基本无效，必须用背景图 + 有尺寸的容器才能生效。
为什么 <img> 标签加 mask-image 没反应
因为 mask-image 作用于整个盒模型（含 padding、border），不是图像内容本身。当 <img> 是响应式（比如 height: auto）且父容器没设高度时，浏览器计算出的遮罩区域常为 0×0，结果就是全透明、啥也不显示。
常见错误现象：mask-image: linear-gradient(...) 写对了，但图片“消失”或边缘毫无渐变感。
- 必须把图片设为容器的
background-image，而非<img>元素 - 该容器必须有明确可计算的尺寸：要么显式写
width和height，要么用aspect-ratio（2026 年已广泛支持） - 别指望
max-width: 100%或width: 100%自动撑开——没高度，mask就没作用域
mask-image: linear-gradient() 的写法与 Safari 兼容陷阱
渐变方向要匹配羽化方向，颜色值必须用灰度：Safari 会静默忽略 transparent 和 rgba()，只认 #000（隐藏）、#fff（显示）、中间灰阶（半透）。
例如左右羽化边缘：
mask-image: linear-gradient(to right, #000 0%, #fff 20%, #fff 80%, #000 100%); -webkit-mask-image: linear-gradient(to right, #000 0%, #fff 20%, #fff 80%, #000 100%);
- 别写
transparent—— 在 Safari 中会被转成#000，导致边缘全黑 - 必须配
mask-repeat: no-repeat和mask-size: 100% 100%，否则渐变会平铺或拉伸失真 - Firefox 目前仍不支持
mask-image的渐变值，声明会被跳过；跨浏览器稳定方案只能是 SVG 遮罩
响应式羽化边缘怎么适配不同屏幕方向
单条 linear-gradient 无法自动感知横竖屏变化。靠媒体查询重写 mask-image 是唯一可靠方式。
- 竖屏时用
to bottom实现上下羽化 - 横屏时切到
to right实现左右羽化 - 不要试图用
orientation媒体查询 —— 它在桌面 Chrome 中已废弃，应改用min-aspect-ratio或具体宽高断点 - 若需动画过渡，避免直接动画
mask-image（不支持），可用mask-position移动渐变起点，或切换类名触发重绘
滚动区域里的渐变羽化遮罩为何会跟着滚动
遮罩必须固定在视口上，不能随内容滚动。常见错误是把 mask-image 加在滚动容器（如 .scroll-area）上。
- 正确结构：外层容器设
overflow: hidden+mask-image，内层设overflow-x: auto并处理子项排布 - 内层滚动容器绝对不能设
mask-image，否则 Safari 下遮罩会失效（已知 WebKit bug） - 如果用
scroll-snap，确保scroll-snap-align设在图片项上，而不是遮罩层
最易被忽略的一点：羽化效果是否生效，和容器有没有“真正渲染出像素”强相关。哪怕写了 background-color，若该容器被 display: none、visibility: hidden 或父级 opacity: 0 影响，mask-image 也会静默失效——它只作用于视觉树中实际绘制的盒模型。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
