iOS Safari中mask-image需同时声明-webkit-mask-image与mask-image、用单行base64内联SVG、设mask-mode:luminance及mask-size:100% 100%/no-repeat，否则静默失效。
移动端用 mask-image 做异形图标，不是加一行 CSS 就能跑通的事——iOS Safari 会直接忽略不合规写法，图标“凭空消失”，连报错都没有。
为什么 mask-image 在 iOS Safari 上完全不显示
这不是兼容性“差”，而是 Safari 对 mask-image 的解析规则极其严格：
-
mask-image单独存在但没配background-image或background-color，结果是透明盒子，视觉上等于没渲染 -
-webkit-mask-image和mask-image必须同时声明、值完全一致，缺一不可 - URL 形式（如
mask-image: url('/icon.svg')）在 Safari 中静默失败，尤其遇到#、空格、未编码的<或换行时直接跳过解析 - Tailwind 的动态语法如
mask-[url(...)]在 Safari 中被当作无效声明，不报错也不生效
必须用 base64 内联 SVG，且编码不能有空格或换行
真机测试确认：只有把 SVG 转成单行 base64，并嵌入 url('data:image/svg+xml;base64,...') 才稳定。
- 原始 SVG 必须移除所有换行、缩进、注释；
<、>、"需 URL 编码（例如<svg→%3Csvg） - 不要用
id引用（如url(#mask)），Safari 不支持外部 ID 解析 - 显式设置
mask-mode: luminance，避免不同浏览器对灰度解释不一致（比如 Chrome 当亮度处理，Firefox 当 Alpha 处理） - 示例有效写法：
.icon { -webkit-mask-image: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0Ij48cGF0aCBkPSJNMCAwaDI0djI0SDB6IiBmaWxsPSIjZmZmIi8+PHBhdGggZD0iTTExIDRoMnYySDExVjR6bTAgNmgycjJIMTFWNnptMCAxMmgycjJIMTFWMnptMCAyNGgydjJIMHYtMnptMCAyMGgydjJIMHYtMnptMCAxNmgydjJIMHYtMnptMCAxMmgydjJIMHYtMnptMCA4aDJ2MkgxMHYtMnptMCA0aDJ2MkgxMHYtMnptMCAwaDJ2MkgxMHYtMiIgZmlsbD0iI2ZmZiIvPjwvc3ZnPg=='); mask-image: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0Ij48cGF0aCBkPSJNMCAwaDI0djI0SDB6IiBmaWxsPSIjZmZmIi8+PHBhdGggZD0iTTExIDRoMnYySDExVjR6bTAgNmgycjJIMTFWNnptMCAxMmgycjJIMTFWMnptMCAyNGgydjJIMHYtMnptMCAyMGgydjJIMHYtMnptMCAxNmgydjJIMHYtMnptMCAxMmgydjJIMHYtMnptMCA4aDJ2MkgxMHYtMnptMCA0aDJ2MkgxMHYtMiIgZmlsbD0iI2ZmZiIvPjwvc3ZnPg=='); mask-mode: luminance; }
mask-size 和 mask-repeat 必须设为 100% + no-repeat
写死像素值（如 mask-size: 24px 24px）在高 DPI 屏幕下必然模糊——因为 CSS px 和物理像素比不是 1:1，遮罩图被拉伸填充。
立即学习“前端免费学习笔记（深入）”；
- 正确做法：
mask-size: 100% 100%+mask-repeat: no-repeat，让遮罩图严格贴合元素盒模型尺寸 - 响应式缩放时，不要调
mask-size，而是用clamp()控制容器宽高，让mask-size: 100% 100%自动适应 - 如果图标需居中对齐，加
mask-position: center，避免因默认左上角对齐导致裁切偏移
颜色控制只能靠 background，不能直接给 mask 上色
mask-image 本身不携带颜色信息，它只决定“哪里透”，颜色必须由底层 background 提供。
- 单色图标：用
background-color: currentColor，再通过父级color变量切换主题色（例如:root { --icon-color: #3b82f6; }+color: var(--icon-color)） - 渐变图标：用
background-image: linear-gradient(...)，但注意 Safari 要求渐变在background侧定义，mask侧只负责形状 - 深色模式适配：不要尝试改
mask-image的颜色，而应监听@media (prefers-color-scheme: dark)改background-color或background-image
最常被忽略的点：mask 不改变盒模型，也不影响布局流——它只是 Alpha 层操作。如果你需要文字环绕异形图标，mask-image 无能为力，得换 shape-outside 或 SVG clipPath。
