一套零依赖的 Base64 动态编码方案先讲个真实场景。你拿到一张设计稿上面有个搜索图标颜色是#333。产品说这个图标在深色模式下要变白在活动页要变橙在禁用态要变灰。你打开原生小程序的 WXML想写svg fillcurrentColor——抱歉没有svg标签。你想在 WXSS 里写mask-image: url(/svg/search.svg)——抱歉iOS 直接给你脸色看。你想用filter: drop-shadow那套黑科技——Android 某个机型上滤镜一失效图标当场消失用户看到一片空白。于是你打开 PS把同一个图标导出了七八个颜色版本文件夹越堆越乱。这篇文章要解决的就是这个事。一、先看清地形原生小程序能走哪条路选方案之前先把硬约束摆到桌面上约束现实WXML 不支持svg标签内联 SVG 这条路堵死WXSS 不能引用本地图片mask-image: url(/svg/x.svg)在 iOS 上大概率失效image支持 data URI唯一稳定可控的入口文件系统 API 可读包内文件wx.getFileSystemManager().readFileSync能读/svg/xxx.svgfilter: drop-shadow部分 Android 机型失效失效即白屏不可靠地形很清楚唯一稳定的路是把 SVG 读出来、改色、编码成 Base64 data URI塞给image的src。听起来不复杂。但要做成能上生产的东西得解决三件事读得省、算得少、出错不白屏。二、整体架构components/Img/ ├── base64.js # 零依赖 UTF-8 → Base64 编码器 ├── index.js # 组件逻辑 双层缓存 改色 ├── index.wxml # image 渲染 降级 └── index.wxss # 尺寸与 rtl 样式数据流长这样svg 名 color ↓ readSvg() ← 读文件rawCache 缓存原始文本 ↓ recolor() ← 正则替换 fill / stroke ↓ svgToDataUri() ← UTF-8 → Base64 ↓ uriCache 缓存 ← key ${svg}|${color} ↓ image src{{svgPlus}}任意环节失败 → 返回→ WXML 用svgPlus || /svg/ svg .svg回退到原始文件。三条防线读盘有缓存编码有缓存出错有降级。三、核心代码3.1 base64.js零依赖 UTF-8 → Base64不引入js-base64之类的库自己实现。surrogate pair 也处理了emoji 不会翻车。// components/Img/base64.js// UTF-8 → Base64零原生依赖constCHARSABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789/;/** 字符串 → UTF-8 字节数组 */functiontoUtf8Bytes(str){constbytes[];for(leti0;istr.length;i){letcstr.charCodeAt(i);if(c0x80){bytes.push(c);}elseif(c0x800){bytes.push(0xc0|(c6),0x80|(c0x3f));}elseif(c0xd800||c0xe000){bytes.push(0xe0|(c12),0x80|((c6)0x3f),0x80|(c0x3f));}else{// surrogate pairemoji 等constc20x10000(((c0x3ff)10)|(str.charCodeAt(i)0x3ff));bytes.push(0xf0|(c218),0x80|((c212)0x3f),0x80|((c26)0x3f),0x80|(c20x3f));}}returnbytes;}/** UTF-8 字节数组 → Base64 字符串 */functionbytesToBase64(bytes){constlenbytes.length;letout;for(leti0;ilen;i3){constb1bytes[i];consthas2i1len;consthas3i2len;constb2has2?bytes[i1]:0;constb3has3?bytes[i2]:0;consttriple(b116)|(b28)|b3;outCHARS[(triple18)63];outCHARS[(triple12)63];outhas2?CHARS[(triple6)63]:;outhas3?CHARS[triple63]:;}returnout;}/** 字符串 → data:image/svgxml;base64,... */functionsvgToDataUri(svgStr){returndata:image/svgxml;base64,${bytesToBase64(toUtf8Bytes(svgStr))};}exportdefaultsvgToDataUri;3.2 index.js组件 双层缓存 改色// components/Img/index.jsimportsvgToDataUrifrom./base64;// ── 模块级缓存整个小程序生命周期内共享 ──constrawCacheObject.create(null);// svg 名 → 原始文本consturiCacheObject.create(null);// ${svg}|${color} → data URI/** 读取并缓存原始 svg 文本 */functionreadSvg(name){if(nameinrawCache)returnrawCache[name];try{constfswx.getFileSystemManager();consttextfs.readFileSync(/svg/${name}.svg,utf-8);rawCache[name]text;returntext;}catch(e){console.error([Img] 读取 svg 失败:,name,e);rawCache[name];// 缓存失败结果避免反复抛错return;}}/** 替换 fill / stroke 颜色跳过 none 和 url(...) 引用 */functionrecolor(svgStr,color){constRE_FILL/fill\s*\s*[](?!none|url\()([^]*)[]/gi;constRE_STROKE/stroke\s*\s*[](?!none|url\()([^]*)[]/gi;returnsvgStr.replace(RE_FILL,fill${color}).replace(RE_STROKE,stroke${color});}Component({properties:{svg:{type:String,value:},color:{type:String,value:},rtl:{type:Boolean,value:false},size:{type:Number,value:3},},data:{svgPlus:,// 改色后的 data URI空串表示走原始文件},observers:{// 只关心 svg 和 colorrtl 交给 WXSS不参与计算svg, color:function(svg,color){this.setData({svgPlus:this.buildUri(svg,color)});},},methods:{/** 生成 data URI任意失败/无需处理都返回 作为回退信号 */buildUri(svg,color){if(!svg||!color)return;constkey${svg}|${color};if(keyinuriCache)returnuriCache[key];constrawreadSvg(svg);if(!raw)return(uriCache[key]);try{return(uriCache[key]svgToDataUri(recolor(raw,color)));}catch(e){console.error([Img] 编码 Base64 失败:,svg,e);return(uriCache[key]);}},},});3.3 index.wxml渲染与降级!--components/Img/index.wxml--imageclasssvg-img {{rtl ? svg-img--rtl : }}style--sz:{{size || 3}}vwsrc{{svgPlus || /svg/ svg .svg}}modeaspectFill/size的默认值已经在properties里设了3WXML 里的|| 3是冗余的可以写成--sz:{{size}}vw。3.4 index.wxss尺寸与 RTL/* components/Img/index.wxss */.svg-img{width:var(--sz,3vw);height:var(--sz,3vw);}.svg-img--rtl{transform:rotateY(180deg);}3.5 使用方式Imgsvgsearchcolor#333size4/Imgsvgarrowcolor#ff6b00size3rtl/把 SVG 文件丢进小程序的/svg/目录收工。没有构建步骤没有配置文件没有依赖安装。四、设计要点解析4.1 为什么用 Base64 而不是 URL 编码data:image/svgxml,后面直接跟 URL 编码的 SVG 也能用。但 URL 编码会把、、、#这些字符一个个转义体积膨胀比 Base64 还明显拼接逻辑也更容易出错。Base64 膨胀约 33%但编码规则确定、无歧义image对它支持稳定。一句话Base64 是笨办法但笨办法不出错。4.2 双层缓存各管一段rawCache避免同一个 SVG 被重复读盘。文件 IO 在小程序里是同步阻塞的能省一次是一次。uriCachekey 是${svg}|${color}避免同一图标同一颜色被重复编码。Base64 是纯 CPU 操作但图标数 × 颜色数这个乘积可能很大缓存之后实际只算一次。两个缓存都是模块级的整个小程序生命周期内共享不是每个组件实例一份。同一个图标在十个页面用也只读一次、编一次。4.3 失败也缓存readSvg失败时把rawCache[name] buildUri失败时把uriCache[key] 。这一步很容易被忽略。如果不缓存失败结果一个坏图标会在每次渲染时反复抛错、反复打日志性能日志里全是噪音。缓存失败等于告诉系统这事已经确认不行了别再试了。4.4 优雅降级永不白屏buildUri返回时WXML 用svgPlus || /svg/ svg .svg回退到原始文件没传color→ 用原始 SVG改色失败 → 用原始 SVG编码失败 → 用原始 SVG最差的情况是颜色没变但图标一定在。这是它比filter: drop-shadow可靠的根本原因——那套黑科技一旦失效图标直接消失用户看到一片空白。4.5 recolor 的边界处理/fill\s*\s*[](?!none|url\()([^]*)[]/gi(?!none)跳过fillnone不把透明区域填成实心(?!url\()跳过fillurl(#gradient)不破坏渐变引用\s*\s*容忍fill red这种带空格的写法对于项目内自己维护的、结构规范的 SVG这个正则够用。如果 SVG 来源不可控建议在构建阶段先做一轮标准化。五、性能与注意事项5.1 性能首次使用某图标一次同步读文件 一次 Base64 编码通常 1~3ms取决于 SVG 大小。后续使用纯查表接近零开销。多组件共享同一图标模块级缓存保证只算一次。5.2 注意事项SVG 必须放在包内/svg/是包内路径不支持网络路径或临时文件路径。控制 SVG 体积Base64 膨胀约 33%单个图标建议控制在 2KB 以内否则 data URI 过大影响image解析。颜色值格式传#333、red、rgb(0,0,0)都行但不要传带引号或分号的值会破坏 SVG 结构。mode的选择图标通常是正方形aspectFill没问题非正方形且不想裁切就改aspectFit。不支持多色 SVG所有非none/url()的fill/stroke会被替换成同一个颜色。多色图标需要另想办法。六、和其他方案的对比方案原生小程序可用换色能力依赖可靠性本方案Base64 动态编码是单色任意换零高WXSSmaskbackground-color否单色零iOS 失效filter: drop-shadow黑科技部分单色零部分 Android 失效miniprogram-iconfontCLI是多色构建工具高依赖 iconfont 工作流uni-appaw-svg等组件否原生不可用多色uni-app—写原生小程序、不想引构建工具链、图标以单色为主——这套方案就是当前手写方案里的天花板。它不依赖任何特殊 CSS 特性只依赖image和文件系统 API确定能跑。七、可选的优化方向缓存 fs 实例wx.getFileSystemManager()每次返回同一个实例模块级存一次即可省一次函数调用。去掉size || 3冗余properties.size默认值已是3。构建期预处理图标数量很大时构建阶段就把 SVG 转成 Base64 写进 JS 常量运行时零 IO。代价是包体积变大、只能换预设颜色。接入 iconfont 工作流图标来自 iconfont 的话用miniprogram-iconfont生成 CSS省掉手写组件还支持多色。八、总结这套方案的核心思想一句话既然原生小程序不能内联 SVG那就把 SVG 变成image能吃的 data URI。难点不在编码本身而在三件事缓存设计模块级双层缓存把 IO 和编码开销压到最低降级策略任意环节失败都回退到原始文件永不白屏边界处理跳过none和url()不破坏渐变和透明区域代码总量不到 150 行零依赖直接复制就能用。项目是原生微信小程序、图标以单色为主、不想引构建工具——这套方案能帮你省下建七八个颜色版本文件夹的功夫。如果这篇文章对你有帮助欢迎点赞收藏。有更好的思路也欢迎在评论区交流。
一套零依赖的 Base64 动态编码方案先讲个真实场景。你拿到一张设计稿上面有个搜索图标颜色是#333。产品说这个图标在深色模式下要变白在活动页要变橙在禁用态要变灰。你打开原生小程序的 WXML想写svg fillcurrentColor——抱歉没有svg标签。你想在 WXSS 里写mask-image: url(/svg/search.svg)——抱歉iOS 直接给你脸色看。你想用filter: drop-shadow那套黑科技——Android 某个机型上滤镜一失效图标当场消失用户看到一片空白。于是你打开 PS把同一个图标导出了七八个颜色版本文件夹越堆越乱。这篇文章要解决的就是这个事。一、先看清地形原生小程序能走哪条路选方案之前先把硬约束摆到桌面上约束现实WXML 不支持svg标签内联 SVG 这条路堵死WXSS 不能引用本地图片mask-image: url(/svg/x.svg)在 iOS 上大概率失效image支持 data URI唯一稳定可控的入口文件系统 API 可读包内文件wx.getFileSystemManager().readFileSync能读/svg/xxx.svgfilter: drop-shadow部分 Android 机型失效失效即白屏不可靠地形很清楚唯一稳定的路是把 SVG 读出来、改色、编码成 Base64 data URI塞给image的src。听起来不复杂。但要做成能上生产的东西得解决三件事读得省、算得少、出错不白屏。二、整体架构components/Img/ ├── base64.js # 零依赖 UTF-8 → Base64 编码器 ├── index.js # 组件逻辑 双层缓存 改色 ├── index.wxml # image 渲染 降级 └── index.wxss # 尺寸与 rtl 样式数据流长这样svg 名 color ↓ readSvg() ← 读文件rawCache 缓存原始文本 ↓ recolor() ← 正则替换 fill / stroke ↓ svgToDataUri() ← UTF-8 → Base64 ↓ uriCache 缓存 ← key ${svg}|${color} ↓ image src{{svgPlus}}任意环节失败 → 返回→ WXML 用svgPlus || /svg/ svg .svg回退到原始文件。三条防线读盘有缓存编码有缓存出错有降级。三、核心代码3.1 base64.js零依赖 UTF-8 → Base64不引入js-base64之类的库自己实现。surrogate pair 也处理了emoji 不会翻车。// components/Img/base64.js// UTF-8 → Base64零原生依赖constCHARSABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789/;/** 字符串 → UTF-8 字节数组 */functiontoUtf8Bytes(str){constbytes[];for(leti0;istr.length;i){letcstr.charCodeAt(i);if(c0x80){bytes.push(c);}elseif(c0x800){bytes.push(0xc0|(c6),0x80|(c0x3f));}elseif(c0xd800||c0xe000){bytes.push(0xe0|(c12),0x80|((c6)0x3f),0x80|(c0x3f));}else{// surrogate pairemoji 等constc20x10000(((c0x3ff)10)|(str.charCodeAt(i)0x3ff));bytes.push(0xf0|(c218),0x80|((c212)0x3f),0x80|((c26)0x3f),0x80|(c20x3f));}}returnbytes;}/** UTF-8 字节数组 → Base64 字符串 */functionbytesToBase64(bytes){constlenbytes.length;letout;for(leti0;ilen;i3){constb1bytes[i];consthas2i1len;consthas3i2len;constb2has2?bytes[i1]:0;constb3has3?bytes[i2]:0;consttriple(b116)|(b28)|b3;outCHARS[(triple18)63];outCHARS[(triple12)63];outhas2?CHARS[(triple6)63]:;outhas3?CHARS[triple63]:;}returnout;}/** 字符串 → data:image/svgxml;base64,... */functionsvgToDataUri(svgStr){returndata:image/svgxml;base64,${bytesToBase64(toUtf8Bytes(svgStr))};}exportdefaultsvgToDataUri;3.2 index.js组件 双层缓存 改色// components/Img/index.jsimportsvgToDataUrifrom./base64;// ── 模块级缓存整个小程序生命周期内共享 ──constrawCacheObject.create(null);// svg 名 → 原始文本consturiCacheObject.create(null);// ${svg}|${color} → data URI/** 读取并缓存原始 svg 文本 */functionreadSvg(name){if(nameinrawCache)returnrawCache[name];try{constfswx.getFileSystemManager();consttextfs.readFileSync(/svg/${name}.svg,utf-8);rawCache[name]text;returntext;}catch(e){console.error([Img] 读取 svg 失败:,name,e);rawCache[name];// 缓存失败结果避免反复抛错return;}}/** 替换 fill / stroke 颜色跳过 none 和 url(...) 引用 */functionrecolor(svgStr,color){constRE_FILL/fill\s*\s*[](?!none|url\()([^]*)[]/gi;constRE_STROKE/stroke\s*\s*[](?!none|url\()([^]*)[]/gi;returnsvgStr.replace(RE_FILL,fill${color}).replace(RE_STROKE,stroke${color});}Component({properties:{svg:{type:String,value:},color:{type:String,value:},rtl:{type:Boolean,value:false},size:{type:Number,value:3},},data:{svgPlus:,// 改色后的 data URI空串表示走原始文件},observers:{// 只关心 svg 和 colorrtl 交给 WXSS不参与计算svg, color:function(svg,color){this.setData({svgPlus:this.buildUri(svg,color)});},},methods:{/** 生成 data URI任意失败/无需处理都返回 作为回退信号 */buildUri(svg,color){if(!svg||!color)return;constkey${svg}|${color};if(keyinuriCache)returnuriCache[key];constrawreadSvg(svg);if(!raw)return(uriCache[key]);try{return(uriCache[key]svgToDataUri(recolor(raw,color)));}catch(e){console.error([Img] 编码 Base64 失败:,svg,e);return(uriCache[key]);}},},});3.3 index.wxml渲染与降级!--components/Img/index.wxml--imageclasssvg-img {{rtl ? svg-img--rtl : }}style--sz:{{size || 3}}vwsrc{{svgPlus || /svg/ svg .svg}}modeaspectFill/size的默认值已经在properties里设了3WXML 里的|| 3是冗余的可以写成--sz:{{size}}vw。3.4 index.wxss尺寸与 RTL/* components/Img/index.wxss */.svg-img{width:var(--sz,3vw);height:var(--sz,3vw);}.svg-img--rtl{transform:rotateY(180deg);}3.5 使用方式Imgsvgsearchcolor#333size4/Imgsvgarrowcolor#ff6b00size3rtl/把 SVG 文件丢进小程序的/svg/目录收工。没有构建步骤没有配置文件没有依赖安装。四、设计要点解析4.1 为什么用 Base64 而不是 URL 编码data:image/svgxml,后面直接跟 URL 编码的 SVG 也能用。但 URL 编码会把、、、#这些字符一个个转义体积膨胀比 Base64 还明显拼接逻辑也更容易出错。Base64 膨胀约 33%但编码规则确定、无歧义image对它支持稳定。一句话Base64 是笨办法但笨办法不出错。4.2 双层缓存各管一段rawCache避免同一个 SVG 被重复读盘。文件 IO 在小程序里是同步阻塞的能省一次是一次。uriCachekey 是${svg}|${color}避免同一图标同一颜色被重复编码。Base64 是纯 CPU 操作但图标数 × 颜色数这个乘积可能很大缓存之后实际只算一次。两个缓存都是模块级的整个小程序生命周期内共享不是每个组件实例一份。同一个图标在十个页面用也只读一次、编一次。4.3 失败也缓存readSvg失败时把rawCache[name] buildUri失败时把uriCache[key] 。这一步很容易被忽略。如果不缓存失败结果一个坏图标会在每次渲染时反复抛错、反复打日志性能日志里全是噪音。缓存失败等于告诉系统这事已经确认不行了别再试了。4.4 优雅降级永不白屏buildUri返回时WXML 用svgPlus || /svg/ svg .svg回退到原始文件没传color→ 用原始 SVG改色失败 → 用原始 SVG编码失败 → 用原始 SVG最差的情况是颜色没变但图标一定在。这是它比filter: drop-shadow可靠的根本原因——那套黑科技一旦失效图标直接消失用户看到一片空白。4.5 recolor 的边界处理/fill\s*\s*[](?!none|url\()([^]*)[]/gi(?!none)跳过fillnone不把透明区域填成实心(?!url\()跳过fillurl(#gradient)不破坏渐变引用\s*\s*容忍fill red这种带空格的写法对于项目内自己维护的、结构规范的 SVG这个正则够用。如果 SVG 来源不可控建议在构建阶段先做一轮标准化。五、性能与注意事项5.1 性能首次使用某图标一次同步读文件 一次 Base64 编码通常 1~3ms取决于 SVG 大小。后续使用纯查表接近零开销。多组件共享同一图标模块级缓存保证只算一次。5.2 注意事项SVG 必须放在包内/svg/是包内路径不支持网络路径或临时文件路径。控制 SVG 体积Base64 膨胀约 33%单个图标建议控制在 2KB 以内否则 data URI 过大影响image解析。颜色值格式传#333、red、rgb(0,0,0)都行但不要传带引号或分号的值会破坏 SVG 结构。mode的选择图标通常是正方形aspectFill没问题非正方形且不想裁切就改aspectFit。不支持多色 SVG所有非none/url()的fill/stroke会被替换成同一个颜色。多色图标需要另想办法。六、和其他方案的对比方案原生小程序可用换色能力依赖可靠性本方案Base64 动态编码是单色任意换零高WXSSmaskbackground-color否单色零iOS 失效filter: drop-shadow黑科技部分单色零部分 Android 失效miniprogram-iconfontCLI是多色构建工具高依赖 iconfont 工作流uni-appaw-svg等组件否原生不可用多色uni-app—写原生小程序、不想引构建工具链、图标以单色为主——这套方案就是当前手写方案里的天花板。它不依赖任何特殊 CSS 特性只依赖image和文件系统 API确定能跑。七、可选的优化方向缓存 fs 实例wx.getFileSystemManager()每次返回同一个实例模块级存一次即可省一次函数调用。去掉size || 3冗余properties.size默认值已是3。构建期预处理图标数量很大时构建阶段就把 SVG 转成 Base64 写进 JS 常量运行时零 IO。代价是包体积变大、只能换预设颜色。接入 iconfont 工作流图标来自 iconfont 的话用miniprogram-iconfont生成 CSS省掉手写组件还支持多色。八、总结这套方案的核心思想一句话既然原生小程序不能内联 SVG那就把 SVG 变成image能吃的 data URI。难点不在编码本身而在三件事缓存设计模块级双层缓存把 IO 和编码开销压到最低降级策略任意环节失败都回退到原始文件永不白屏边界处理跳过none和url()不破坏渐变和透明区域代码总量不到 150 行零依赖直接复制就能用。项目是原生微信小程序、图标以单色为主、不想引构建工具——这套方案能帮你省下建七八个颜色版本文件夹的功夫。如果这篇文章对你有帮助欢迎点赞收藏。有更好的思路也欢迎在评论区交流。
