Safari 15.4前不支持mask-image，仅支持url(#svg-mask)形式；需用内联SVG设maskUnits="userSpaceOnUse"、避免luminance、注意fill/opacity影响及ID引用失效。
mask-image 在 Chrome/Firefox 里正常，Safari 15.4 之前不支持
Safari 对 mask-image 的支持长期滞后，尤其在 iOS 15.4 之前的系统中完全不识别该属性，即使写了也会静默失效。这不是写法问题，是引擎限制 —— WebKit 直到 Safari 15.4 才开始部分支持 CSS Masking Level 1，且仅限于 mask-image: url(#svg-mask) 这种引用 SVG 的形式，纯 CSS 渐变或图片路径（如 mask-image: linear-gradient(...)）仍被忽略。
- 验证是否生效：检查 Safari 开发者工具的「Computed」面板，看
mask-image是否显示为none或灰色禁用状态 - 绕过方式：必须用内联 SVG 定义
<mask></mask>，再通过mask-image: url(#my-mask)引用，不能用外部 SVG 文件或 base64 - 注意 ID 作用域：SVG
<mask></mask>必须和目标元素在同一个 HTML 文档内（或同个 Shadow DOM），跨 iframe 或 CSS 模块加载会断开引用
用 SVG 实现圆角遮罩时，maskUnits="userSpaceOnUse" 是关键
默认情况下 SVG <mask></mask> 使用 objectBoundingBox 坐标系（0–1 范围），但 CSS 元素尺寸不确定时，这种相对坐标会导致遮罩错位或缩放异常。比如想给一个宽高不定的卡片加圆角遮罩，直接写 <rect rx="8" ry="8"></rect> 在 objectBoundingBox 下会被压缩成极小区域。
- 强制使用像素坐标：在
<mask></mask> 标签上显式声明 maskUnits="userSpaceOnUse"
- 配套设置
width/height：值需覆盖目标元素最大可能尺寸（例如设为 width="2000" height="2000"），避免裁剪
- 示例片段：
<svg width="0" height="0">
<mask id="rounded" maskUnits="userSpaceOnUse" width="2000" height="2000">
<rect width="2000" height="2000" rx="12" ry="12"/>
</mask>
</svg>
mask-mode: alpha 和 luminance 在 Safari 中行为不一致
Safari 对 mask-mode 的解析和 Chrome/Firefox 不同：它只认 mask-mode: alpha（默认值），而把 luminance 当作无效值降级处理，导致灰度图遮罩在 Safari 里变成全白或全黑 —— 尤其影响用 PNG 灰度图做遮罩的场景。
- 安全做法：统一用
mask-mode: alpha，并确保遮罩图像本身是带透明通道的 PNG（而非靠灰度值控制透明度）
- 如果必须依赖亮度（比如用 JPG 做遮罩），改用 SVG
<fecolormatrix></fecolormatrix> 预处理：在 SVG <mask></mask> 内嵌滤镜，把亮度转为 alpha
- 避免在 CSS 里写
mask-mode: luminance，Safari 会忽略整条声明，连带后面的 mask-image 也可能失效
SVG 遮罩元素的 fill 和 opacity 会影响最终透明度
很多人以为 SVG <mask></mask> 里只看形状，其实 fill 颜色的 alpha 值、opacity、甚至父容器的 opacity 都会参与计算 —— 这不是 bug，是规范定义的叠加逻辑，但容易被忽略。
立即学习“前端免费学习笔记（深入）”；
-
fill="black" 表示完全遮挡（alpha=0），fill="white" 表示完全显示（alpha=1），fill="gray" 则产生半透效果
- 如果设置了
opacity="0.8"，即使 fill="white"，最终遮罩强度也只有 80%，内容会轻微“漏光”
- 调试技巧：临时把 SVG
<mask></mask> 提到页面可视区域，加上 style="border:1px solid red"，直接观察遮罩图形是否按预期渲染
实际项目里最常卡住的，是 Safari 中 SVG <mask></mask> 的 ID 引用失效 —— 看似代码没错，但因为 SVG 在 display: none 包裹、又或者被 JS 动态插入后未触发重绘，都会让 url(#xxx) 找不到目标。这种情况没有错误提示，只能靠手动把 SVG 放到
maskUnits="userSpaceOnUse" 是关键
默认情况下 SVG <mask></mask> 使用 objectBoundingBox 坐标系（0–1 范围），但 CSS 元素尺寸不确定时，这种相对坐标会导致遮罩错位或缩放异常。比如想给一个宽高不定的卡片加圆角遮罩，直接写 <rect rx="8" ry="8"></rect> 在 objectBoundingBox 下会被压缩成极小区域。
- 强制使用像素坐标：在
<mask></mask>标签上显式声明maskUnits="userSpaceOnUse" - 配套设置
width/height：值需覆盖目标元素最大可能尺寸（例如设为width="2000" height="2000"），避免裁剪 - 示例片段：
<svg width="0" height="0"> <mask id="rounded" maskUnits="userSpaceOnUse" width="2000" height="2000"> <rect width="2000" height="2000" rx="12" ry="12"/> </mask> </svg>
mask-mode: alpha 和 luminance 在 Safari 中行为不一致
Safari 对 mask-mode 的解析和 Chrome/Firefox 不同：它只认 mask-mode: alpha（默认值），而把 luminance 当作无效值降级处理，导致灰度图遮罩在 Safari 里变成全白或全黑 —— 尤其影响用 PNG 灰度图做遮罩的场景。
- 安全做法：统一用
mask-mode: alpha，并确保遮罩图像本身是带透明通道的 PNG（而非靠灰度值控制透明度） - 如果必须依赖亮度（比如用 JPG 做遮罩），改用 SVG
<fecolormatrix></fecolormatrix>预处理：在 SVG<mask></mask>内嵌滤镜，把亮度转为 alpha - 避免在 CSS 里写
mask-mode: luminance，Safari 会忽略整条声明，连带后面的mask-image也可能失效
SVG 遮罩元素的 fill 和 opacity 会影响最终透明度
很多人以为 SVG <mask></mask> 里只看形状，其实 fill 颜色的 alpha 值、opacity、甚至父容器的 opacity 都会参与计算 —— 这不是 bug，是规范定义的叠加逻辑，但容易被忽略。
立即学习“前端免费学习笔记（深入）”；
-
fill="black"表示完全遮挡（alpha=0），fill="white"表示完全显示（alpha=1），fill="gray"则产生半透效果 - 如果设置了
opacity="0.8"，即使fill="white"，最终遮罩强度也只有 80%，内容会轻微“漏光” - 调试技巧：临时把 SVG
<mask></mask>提到页面可视区域，加上style="border:1px solid red"，直接观察遮罩图形是否按预期渲染
<mask></mask> 的 ID 引用失效 —— 看似代码没错，但因为 SVG 在 display: none 包裹、又或者被 JS 动态插入后未触发重绘，都会让 url(#xxx) 找不到目标。这种情况没有错误提示，只能靠手动把 SVG 放到 
