svg 是目前唯一跨 chrome/firefox/safari/edge 稳定实现真实 alpha 渐变遮罩的方案；需内联 svg、 置于 中、用十六进制色值定义 并填充 ，html 元素通过 -webkit-mask: url(#fademask); mask: url(#fademask); 应用，且目标元素须有明确宽高。
直接用 SVG <mask></mask> 是目前唯一能在 Chrome、Firefox、Safari、Edge 四个现代浏览器中稳定实现**真实 Alpha 渐变遮罩**的方案，mask-image: linear-gradient() 在 Firefox 中被忽略、在 Safari 中 transparent 被转成 #000 导致全显，别碰。
怎么写一个可复用的渐变蒙版 SVG
把 <svg></svg> 内联在 HTML 顶部（不能外链），设 width="0" height="0" 隐藏，所有定义放在 <defs></defs> 里：
-
<mask id="fadeMask"></mask>必须有id，且只能在<defs></defs>内声明，否则无法被引用 - 渐变必须用
<lineargradient></lineargradient>或<radialgradient></radialgradient>，stop-color只能是十六进制色值：#000（隐藏）、#fff（显示）、#808080（50% 透明）——禁用black、white、rgba()、transparent - 渐变要填充到一个图形上（如
<rect></rect>），否则不生效；<rect width="100%" height="100%" fill="url(#fadeGrad)"></rect>是标准写法 - 不需要写
mask-type="luminance"（默认就是），但加了更稳
示例结构：
<svg width="0" height="0"><defs><lineargradient id="fadeGrad" x1="0" y1="0" x2="0" y2="1"><stop offset="0%" stop-color="#000"></stop><stop offset="100%" stop-color="#fff"></stop></lineargradient><mask id="fadeMask"><rect width="100%" height="100%" fill="url(#fadeGrad)"></rect></mask></defs></svg>
怎么把蒙版应用到 HTML 元素或 SVG 图形上
关键区别在于：HTML 元素靠 CSS，SVG 元素靠属性，且前缀不能少：
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 对
<div>、<code><img>等 HTML 元素，必须同时写：-webkit-mask: url(#fadeMask); mask: url(#fadeMask); - 对 SVG 内部元素（如
<image></image>、<g></g>），直接加属性：mask="url(#fadeMask)" - 目标元素必须有明确宽高（如
width: 300px; height: 200px;或aspect-ratio: 4/3），否则蒙版坐标系失准，拉伸错位 - 不要对
<img>标签直接加mask属性——它会作用在 img 盒模型上（含 margin/border），应改用background-image+ 容器方式 - 目标元素没有背景（
background-color或background-image）——<mask></mask>只控制背景的 Alpha，透明底色下什么也看不到 - 父容器设置了
overflow: hidden，而蒙版区域超出父盒边界，直接被裁掉；临时改成overflow: visible排查 - 用了实验性属性如
mask-border、mask-composite——这些在 Safari/Firefox 中基本不支持，删掉再试 - 它不改变真实 Alpha，只是盖一层，所以
rgba(0,0,0,0.7)、transparent都能用，无浏览器差异 - 容器设
position: relative，伪元素设content: ""+position: absolute+top: 0; left: 0; width: 100%; height: 100% - 响应式下注意容器尺寸稳定，否则伪元素可能拉伸错位
- 本质是“盖层”，不是“挖洞”——做不了镂空文字、Alpha 裁剪等真遮罩场景
为什么蒙版没反应？先查这三处硬限制
90% 的“不生效”不是代码错，而是被底层规则卡住：
另外，<mask></mask> 内图形的坐标系以目标元素左上角为原点，单位是像素或百分比，和 SVG 自身 viewBox 无关；若需像素级精准控制，把 <mask></mask> 的 maskUnits 设为 userSpaceOnUse（默认是 objectBoundingBox）。
想快速模拟遮罩效果？用伪元素更省事
如果你只是需要“视觉上像遮罩”（比如图片上叠一层黑→透明渐变来突出文字），::before + background: linear-gradient() 是更快、更兼容、更好调的方案：
真正需要精确 Alpha 控制（比如导出带透明通道的截图、配合 WebGL 合成、实现边缘羽化抠图），<mask></mask> 是绕不开的路径，但得接受它必须内联、必须灰度、必须配宽高这三个硬约束。
