Tailwind 中 mask-image 默认不可用，需手动扩展配置或使用插件支持 SVG 遮罩；Safari 仅兼容 base64 编码的 -webkit-mask-image 和 mask-image 分开写法；currentColor 变色仅在内联 SVG 或 mask-image+base64（全用 currentColor）时生效。
mask-image 在 Tailwind 中默认不可用，必须手动扩展
Tailwind CSS 4.1 虽然引入了 mask-image- 工具类（如 mask-image-gradient-to-b），但仅限于渐变和径向遮罩，不支持自定义 SVG 遮罩。如果你要复用 mask-image: url(...)，它不会被自动编译进 CSS —— 因为 Tailwind 默认不扫描自定义 URL 值。
正确做法是往 tailwind.config.js 的 theme.extend.backgroundImage 或 @layer utilities 中显式注册：
- 用在线工具（如 svg2base64）把 SVG 转成 base64，删掉 XML 声明和换行
- 确保 SVG 内所有
fill和stroke都是currentColor，且图形为纯黑+透明（单色） - 注册时注意引号嵌套：双引号包裹整个
url('...')，内部单引号包 base64 字符串
示例配置：
module.exports = {
theme: {
extend: {
backgroundImage: {
'icon-search': "url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0Ij48cGF0aCBkPSJNMTUuNSA2LjVhNi41IDYuNSAwIDAgMS05IDEzLjEgMiAyIDAgMCAwLTEuNS0uNSAxMCAxMCAwIDAgMC0xLjUgOS41IDYgNiAwIDAgMS0xMi02IDYgNiAwIDAgMSAxMy41LTYuNSA2LjUgNi41IDAgMCAxIDYuNSAxMy41eiIgZmlsbD0iY3VycmVudENvbG9yIi8+PC9zdmc+')",
}
}
}
}
mask-[url(...)] 类在 Safari 中失效的三个硬伤
Safari 对 mask-image 的实现最保守，直接写 mask-[url('/icons/search.svg')] 几乎必挂。常见失败点：
立即学习“前端免费学习笔记（深入）”；
-
mask-image: url()不接受未编码的#符号（比如url("data:image/svg+xml;charset=utf8,<svg...fill>")</svg...fill>会解析失败）→ 必须用 base64 - 不识别
mask复合属性，只认-webkit-mask-image和mask-image分开写 - 拒绝
mask-[...]这种动态值语法（即使你用mask-[url('...')]），它只吃静态类名或已注册的backgroundImage键
所以 Safari 兼容写法只能是：class="bg-icon-search mask-image-[url('data:image/svg+xml;base64,...')] -webkit-mask-image-[url('data:image/svg+xml;base64,...')]"，且 base64 必须完全一致。
用插件统一管理 SVG 遮罩类，避免重复粘贴 base64
每次改图标都要重转 base64、手写两遍 URL、再塞进 config，太容易出错。更可持续的做法是写一个 Tailwind 插件，把 SVG 文件路径映射成工具类。
例如创建 plugins/mask-icons.js：
const plugin = require('tailwindcss/plugin')
const fs = require('fs')
const path = require('path')
module.exports = plugin(function({ addUtilities, theme }) {
const iconsDir = path.resolve(__dirname, '../src/assets/icons')
const iconFiles = fs.readdirSync(iconsDir).filter(f => f.endsWith('.svg'))
const utilities = {}
iconFiles.forEach(file => {
const name = file.replace('.svg', '')
const content = fs.readFileSync(path.join(iconsDir, file), 'utf8')
.replace(/<\?xml[^>]*>/, '') // 删 XML 声明
.replace(/\s+/g, ' ') // 合并空白
.trim()
const base64 = Buffer.from(content).toString('base64')
utilities[`.mask-icon-${name}`] = {
'-webkit-mask-image': `url('data:image/svg+xml;base64,${base64}')`,
'mask-image': `url('data:image/svg+xml;base64,${base64}')`,
'mask-repeat': 'no-repeat',
'mask-size': 'contain',
'mask-position': 'center'
}
})
addUtilities(utilities)
})
然后在 tailwind.config.js 的 plugins 数组里引入它，HTML 中就能直接用 mask-icon-search 了。
currentColor 动态变色只在内联或 mask-image 场景生效
很多人试过把 SVG 当作 <img src="search.svg"> 放进去，再加 text-red-500，结果图标不变色——这是因为 <img> 是独立文档上下文，currentColor 继承链被切断。
真正起作用的只有两种方式：
- SVG 内联写在 HTML 里：
<svg class="w-5 h-5 text-blue-600"><path fill="currentColor" ...></svg> - 用
mask-image+ base64 SVG，且 SVG 源码中所有颜色属性都设为currentColor
别漏掉这个细节：哪怕只有一处 fill="#000"，整个图标的颜色继承就失效了。
