接手一个 uniapp 项目的时候产品丢过来一份带三十多个图标的视觉稿让我在微信小程序里实现。第一反应当然是引 iconfont 字体图标在 H5 项目里这东西几乎是零成本复制一段 CSS 就能用。结果开发工具里跑得挺欢一预览到真机满屏方块。更麻烦的是这个项目已经进入提测阶段换方案意味着所有页面都得动一遍。这篇文章不打算科普 iconfont 是什么而是把“在 uniapp 项目里引入 iconfont 字体图标并让它在微信小程序端稳定可用”这条链路完整拆开。我会讲清楚选型、引入方式、微信小程序的加载限制以及我实际排查“白屏/方块”问题时的完整思路。如果你正在被小程序图标问题折磨这篇应该能帮你少走不少弯路。1. 为什么小程序端的图标方案绕不开 iconfont1.1 先对比一下几种图标方案的取舍在动手之前很多人的直觉是微信小程序里用图标直接切图不就行了确实可以但项目一多问题就来了。切图方案的核心问题是多端适配。同一个图标为了兼容不同 DPR通常要准备 1x、2x、3x 三套图光命名就要花点心思要是产品中途要换图标颜色就得重新导出。更不用说一张张图片挤进 2MB 主包体积后的罪恶感了。SVG 方案在 H5 里体验很好但微信小程序对动态 SVG 的支持并不友好尤其是use引用外部 symbol 的方式在多数小程序基础库下都容易出兼容问题真机上偶发不渲染。uni-app 的 HBuilderX 虽然能对部分 SVG 做处理但坑比想象中多矢量图里夹杂少量位图信息时经常直接编译失败。字体图标本质上是把图标做成字体文件然后用文字的方式渲染。它在小程序端的优势非常明显单个 ttf 文件颜色可以由 CSS 的color控制大小用font-size控制不引入额外图片请求代码里维护的只是一串类名。这也是为什么很多 uniapp 老项目最终都会落到 iconfont 上。1.2 font class 方式在小程序里的渲染原理font class 方式能工作靠的是 CSS 的font-face声明一个自定义字体族比如font-face { font-family: iconfont; src: url(iconfont.ttf?t123456) format(truetype); }声明之后每个图标本质上是一个字符编码。font class 方式进一步把这些字符编码包装成了伪元素.icon-home::before { font-family: iconfont; content: \e601; }你在页面里写text classiconfont icon-home/text浏览器或者小程序运行环境就会把.icon-home::before渲染成一个文字而这个文字的字体是 iconfont所以显示出来的就是一个图形。WXSS 对::before伪元素是支持的所以这套机制在微信小程序里天然能跑通——前提是font-face里的字体源正确加载了。后面要讲的坑几乎全部集中在这个“加载”环节。1.3 三种接入方式的取舍iconfont 平台有三种使用方式Unicode、Font class、Symbol。方式实现原理小程序端兼容性推荐度Unicode直接写字符实体例如#xe601;可用模板里难维护低Font classCSS 伪元素注入字符编码可用最推荐高SymbolSVG 雪碧图 use引用兼容性不稳定低Unicode 方式的问题在于可读性页面里出现一坨字符实体谁看了都头疼Symbol 方式在小程序端经常碰到use引用不生效的问题而 font class 方式对模板、样式、JS 动态绑定都非常友好。所以我在项目里最终采用的就是 font class 方案后面所有内容也围绕这个方式展开。2. 从挑图标到下载字体包工程选型阶段就决定生死2.1 只挑实际用到的图标不要贪多很多人在阿里的 iconfont 平台上一打开图标库先不管三七二十一全选加进购物车下载下来再说。这是后面包体积失控的第一个隐患。一个全量字体文件通常有 150KB 到 300KB你可能实际用到的不到二十个图标剩下一大半都是无效载荷。把没用的字符编码从字体里剔除文件大小可能直接从 200KB 降到 10KB 左右。这个差异在小程序 2MB 主包限制下完全是两个概念。所以从 pick 图标开始就应该严格按设计稿里的实际清单来先整理一份“用到的图标名字列表”再到平台里一个一个添加。图标多的时候可以在项目里建分组按业务模块区分方便后续维护。2.2 下载包里哪些文件真正有用在 iconfont 平台选择 Font class 方式下载得到的包里有demo.css、demo_index.html、iconfont.css以及一堆字体文件比如iconfont.eoticonfont.svgiconfont.ttficonfont.wofficonfont.woff2这些文件不是全都有用。.eot是给老版本 IE 用的.svg是给早期 iOS 用的现代场景下基本可以无视。微信小程序端最稳的是.ttf部分基础库对.woff的兼容性在不同安卓机型上表现不一为了避免玄学问题我一般只保留.ttf并在 CSS 的src里也只保留truetype这一条。如果你发现下载包里没有.ttf可以在 iconfont 平台的项目设置里调整“字体格式”选项确保勾选了 TTF。2.3 把字体文件安排进 uniapp 工程推荐的项目目录结构是单独建一个目录比如common/iconfont里面放iconfont.css和iconfont.ttfsrc/common/iconfont/ ├── iconfont.css └── iconfont.ttf然后把这个 css 全局引入。uniapp 项目里最稳妥的做法是在App.vue的style里引入因为App.vue的样式默认是全局生效不会被scoped限制style import ./common/iconfont/iconfont.css; /style这里有个容易被忽略的坑如果你把import放到某个页面的style scoped里编译后字体文件的相对路径可能会基于当前页面目录去解析导致在真机上找不到字体文件。局部页面的图标正常其他页面的图标全是方块。所以 iconfont 的全局样式就老老实实放在App.vue的全局 style 里。3. 微信小程序的字体加载机制与路径问题3.1 为什么 H5 里好好的相对路径到小程序里就失效很多人的第一版做法是把 iconfont 下载包里的 css 原封不动拿过来里面src写的是相对路径font-face { font-family: iconfont; src: url(iconfont.ttf?t123456) format(truetype); }这套写法在 H5 页面里完全没问题浏览器会顺着相对路径去请求字体文件。但微信小程序不是浏览器它的 WXSS 对 CSS 里 URL 资源的处理能力非常弱。uniapp 编译器不会像 webpack 处理图片那样把这个url()里的字体文件自动打包成一个可用的资源引用。结果是开发工具里因为本地文件能直接读取看起来是正常的等到了真机上小程序环境根本不知道这个相对路径对应哪个资源字体自然加载失败图标就退化成一个个方框或者干脆什么都不显示。3.2 三套可用方案base64 内嵌、网络地址、loadFontFace针对这个限制我从项目实践里总结出三种比较靠谱的姿势。第一套把字体文件转成 base64 内嵌到 CSS 里这是最省心、也最稳的方案不依赖外部域名不受微信小程序合法域名校验的限制。做法很简单把.ttf文件转成 base64 字符串然后拼到src里font-face { font-family: iconfont; src: url(data:font/truetype;charsetutf-8;base64,AAEAAAA...) format(truetype); }在终端里可以先转出 base64 文本base64 -i iconfont.ttf -o iconfont_base64.txt然后把内容替换进iconfont.css。这种方案的缺点很直白base64 会让字体文件体积膨胀大约 33%而且全部写进 CSS 后这个 css 文件本身会变大不少。但它换来的是一劳永逸的稳定性特别适合一个项目里图标种类有限、变化不频繁的场景。第二套把字体放到 CDN使用网络地址加载如果你对体积非常敏感可以考虑把iconfont.ttf传到自己的 CDN然后 CSS 里写完整 HTTPS 地址font-face { font-family: iconfont; src: url(https://your-cdn.example.com/fonts/iconfont.ttf) format(truetype); }但微信小程序对网络资源有严格校验。字体文件请求会被认为是下载类请求需要在小程序公众平台后台的“开发管理-服务器域名”里配置 downloadFile 合法域名。如果只是本地调试要在微信开发者工具的“详情-本地设置”里勾选“不校验合法域名、web-view业务域名、TLS 版本以及 HTTPS 证书”。我记得很久之前有个项目忘记配这个域名结果图标只在开发工具里显示真机上一片空白排查了半天才发现是域名校验的问题。第三套用 wx.loadFontFace 动态加载微信小程序官方提供了wx.loadFontFace接口可以在运行时加载网络字体。这个 API 的好处是加载时机可控、页面切换时不阻塞渲染适合字体文件较大、只在个别页面用到的场景。但它同样走网络请求域名校验问题绕不开而且加载是异步的首次渲染时图标会出现短暂空白闪烁。我在项目里只在“某个独立活动页必须用一个特殊字体”时用过普通的 iconfont 集成不推荐优先考虑它。3.3 打包体积临界点base64 膨胀与 2MB 主包限制uniapp 编译微信小程序时主包体积限制是 2MB。网上经常看到有人报错source size 2612kb exceed max limit 2mb这种问题很多时候就是 iconfont 的 base64 体积惹的祸。计算一下如果一个全量 iconfont 字体文件是 250KB转成 base64 后大约是 333KB。这还只是一个字体文件。如果项目中再有一些引用的本地图片、公共 js 库很容易逼近体积红线。控制体积的几个关键手段按优先级我建议这样做从源头收紧下载图标时只挑实际使用的这比任何后端压缩都管用因为我见过一百个图标的字体文件压缩到只剩 15KB 后效果依旧完美。使用字体子集化工具如果已经下载了全量字体文件可以用font-spider这类工具分析出真正被content引用的字符生成只有这些字符的新字体文件npx font-spider ./index.html前提是你准备一个包含所有图标类名的临时 HTML 文件让工具去抓取。把不常用的页面拆成微信小程序分包如果你用的是 base64 方案且图标数量较多可以把一部份图标的 CSS 从App.vue挪到对应的分包页面里这样至少不会把所有体积都堆进主包。但要注意同一样字体被复制到多个分包总包体积未必划算操作前先算一笔账。最后才考虑网络字体方案网络字体不占用本地包体积但要接受字体加载延迟和域名配置成本。如果项目对首次渲染要求很高需要配合骨架屏或者按需加载去优化体验。4. 封装 Icon 组件日常开发中最高频的几类用法4.1 一个基础 Icon 组件应该长什么样直接在页面模板里写text classiconfont icon-home不是不行但时间久了你会发现每个页面都要关心前缀、样式、事件代码十分零散。我习惯封装一个Icon组件把细节收敛起来。template text classiconfont :classicon- name :style{ fontSize: realSize, color: color } click$emit(click, $event) /text /template script export default { name: AppIcon, props: { name: { type: String, required: true }, size: { type: Number, default: 32 }, color: { type: String, default: } }, computed: { realSize() { return this.size rpx } } } /script这里有两个细节值得注意微信小程序里的text组件和 HTML 的i标签行为不完全一样它的默认font-size在某些机型上会被重置。所以封装组件时最好不要依赖继承字号显式设置fontSize是最稳妥的。颜色同样要显式传不加color时字号可以继承颜色却未必符合预期尤其当页面里其他元素有独立文字颜色时。4.2 动态图标、循环渲染和状态切换的写法项目里最常遇到的不是静态图标而是动态图标。比如列表数据里每个 item 的图标名来自接口或者点击按钮后图标要在“展开/收起”之间切换。动态绑定的写法注意别漏掉iconfont这个基础类AppIcon :nameitem.iconName :size28 color#333 /如果你是在v-for里使用且图标名来自接口字段我建议使用数组形式绑定类名避免字符串拼接可能带来的前后空格问题text :class[iconfont, icon- item.iconName]/text状态切换的时候常见做法是计算属性里根据条件返回不同的 namecomputed: { iconName() { return this.expanded ? fold : unfold } }这种方式比在模板里写一堆v-if分支清晰得多后续要加第三种状态时也只改一处计算逻辑。4.3 tabBar、多色图标等边角问题老实说字体图标并不是万能的。微信小程序的原生 tabBar 只支持图片格式iconPath必须是本地 png/jpg 路径网络图片、base64 图片都不行。所以 tabBar 里的图标基本还是要走切图路线。如果你特别想用字体图标方案只能通过自定义 tabBar 组件实现但需要自己处理页面切换、选中状态、安全区适配这些细节成本并不低。我的项目里是直接让设计导出 png 的。另一个问题是多色图标。font class 方式渲染的图标颜色完全由 CSS 的color控制所以它本质上是单色图标。iconfont 平台里很多精美图标是多色的这类图标如果坚持用字体方案会发现颜色永远不对。处理方式有几种找同图形的单色版本或者把多色图标单独截成小图。不要把多色图标强行塞进 font class 里我试过一次最后不得不重新走图片方案白折腾一轮。5. 一次真实的白屏排查开发工具正常、真机不显示5.1 从“显示方块”到锁定字体加载失败我印象最深的一次是项目已经准备提测了同事突然跑过来告诉我“首页图标在安卓真机上全是方块”。开发工具里看是完全正常的预览二维码扫出来却不正常。遇到这种问题第一件事不是改代码而是确认现象的真实原因。我当时按这三步走打开微信开发者工具的“真机调试”把页面跑起来看 console 里有没有字体加载失败的报错。在开发者工具的 Sources 面板里检查一下iconfont.css是不是真的被编译进去了字体文件有没有作为一个资源被打包。在页面样式里搜索font-face确认它声明的src在真机环境下还能不能访问。最终问题定位得很清晰CSS 里的src是相对路径url(iconfont.ttf)H5 端能正常加载但小程序真机上找不到对应文件整个font-face声明就形同虚设图标自然全部塌方成方块。5.2 修复过程相对路径换成 base64步骤全记录决定用 base64 方案后我操作的完整过程是这样第一步先备份原来的iconfont.css避免改一半想回退找不到原文件。第二步把字体文件转成 base64base64 -i iconfont.ttf -o iconfont_base64.txt第三步打开生成的文件把整段 base64 字符串复制出来替换掉iconfont.css里的srcfont-face { font-family: iconfont; src: url(data:font/truetype;charsetutf-8;base64,AAEAAAA...) format(truetype); }第四步删掉工程里对原iconfont.ttf的引用避免 HBuilderX 打包时仍然把字体文件误塞进包里占体积。第五步微信开发者工具里清一次缓存“工具-清除缓存-全部清除”然后重新编译、真机预览。这里我说一个特别实际的排查点改了 CSS 之后开发工具如果还在用旧缓存页面显示正常很容易让人误以为已经修复完成。但实际上真机可能还是旧代码。所以提交前一定要清缓存、重新预览最好换一台之前没连着开发工具的测试机扫码验证。5.3 预防复发工程层面的几个固定习惯这个坑踩过一次之后我后续所有 uniapp 小程序项目都固定了几个习惯iconfont 的 CSS 永远放在App.vue全局样式里不放进单个页面的 scoped 样式。字体文件进工程之前先检查src是不是 base64如果是相对路径当场处理不等到真机出问题再补。下载图标时只选实际使用的并把图标分组管理这样即便以后要生成新字体文件改动范围可控。每次改完 iconfont 相关文件都走一遍“清缓存-重新编译-真机预览”三步这不是矫情是真机环境才有最终发言权。平时开发时真机上出现图标问题的概率并不高但一旦出了排查成本往往远高于从一开始就采用稳妥方案的代价。我在实际项目里还有一个小技巧如果一个页面有大量动态图标且图标数量经常变动可以在接口数据里直接返回图标名字前端只维护一套映射。这样即使后续图标更换也不会牵扯到样式文件只要 iconfont 平台侧重新生成了对应的字符编码更新 CSS 声明即可。这样的工作方式在交付给别的同事接手时也能减少很多沟通成本。 
长河君 · 2026/10/9 21:51:34 · 阅读 1.2k uniapp接入iconfont字体图标，搞定微信小程序真机显示方块问题
接手一个 uniapp 项目的时候产品丢过来一份带三十多个图标的视觉稿让我在微信小程序里实现。第一反应当然是引 iconfont 字体图标在 H5 项目里这东西几乎是零成本复制一段 CSS 就能用。结果开发工具里跑得挺欢一预览到真机满屏方块。更麻烦的是这个项目已经进入提测阶段换方案意味着所有页面都得动一遍。这篇文章不打算科普 iconfont 是什么而是把“在 uniapp 项目里引入 iconfont 字体图标并让它在微信小程序端稳定可用”这条链路完整拆开。我会讲清楚选型、引入方式、微信小程序的加载限制以及我实际排查“白屏/方块”问题时的完整思路。如果你正在被小程序图标问题折磨这篇应该能帮你少走不少弯路。1. 为什么小程序端的图标方案绕不开 iconfont1.1 先对比一下几种图标方案的取舍在动手之前很多人的直觉是微信小程序里用图标直接切图不就行了确实可以但项目一多问题就来了。切图方案的核心问题是多端适配。同一个图标为了兼容不同 DPR通常要准备 1x、2x、3x 三套图光命名就要花点心思要是产品中途要换图标颜色就得重新导出。更不用说一张张图片挤进 2MB 主包体积后的罪恶感了。SVG 方案在 H5 里体验很好但微信小程序对动态 SVG 的支持并不友好尤其是use引用外部 symbol 的方式在多数小程序基础库下都容易出兼容问题真机上偶发不渲染。uni-app 的 HBuilderX 虽然能对部分 SVG 做处理但坑比想象中多矢量图里夹杂少量位图信息时经常直接编译失败。字体图标本质上是把图标做成字体文件然后用文字的方式渲染。它在小程序端的优势非常明显单个 ttf 文件颜色可以由 CSS 的color控制大小用font-size控制不引入额外图片请求代码里维护的只是一串类名。这也是为什么很多 uniapp 老项目最终都会落到 iconfont 上。1.2 font class 方式在小程序里的渲染原理font class 方式能工作靠的是 CSS 的font-face声明一个自定义字体族比如font-face { font-family: iconfont; src: url(iconfont.ttf?t123456) format(truetype); }声明之后每个图标本质上是一个字符编码。font class 方式进一步把这些字符编码包装成了伪元素.icon-home::before { font-family: iconfont; content: \e601; }你在页面里写text classiconfont icon-home/text浏览器或者小程序运行环境就会把.icon-home::before渲染成一个文字而这个文字的字体是 iconfont所以显示出来的就是一个图形。WXSS 对::before伪元素是支持的所以这套机制在微信小程序里天然能跑通——前提是font-face里的字体源正确加载了。后面要讲的坑几乎全部集中在这个“加载”环节。1.3 三种接入方式的取舍iconfont 平台有三种使用方式Unicode、Font class、Symbol。方式实现原理小程序端兼容性推荐度Unicode直接写字符实体例如#xe601;可用模板里难维护低Font classCSS 伪元素注入字符编码可用最推荐高SymbolSVG 雪碧图 use引用兼容性不稳定低Unicode 方式的问题在于可读性页面里出现一坨字符实体谁看了都头疼Symbol 方式在小程序端经常碰到use引用不生效的问题而 font class 方式对模板、样式、JS 动态绑定都非常友好。所以我在项目里最终采用的就是 font class 方案后面所有内容也围绕这个方式展开。2. 从挑图标到下载字体包工程选型阶段就决定生死2.1 只挑实际用到的图标不要贪多很多人在阿里的 iconfont 平台上一打开图标库先不管三七二十一全选加进购物车下载下来再说。这是后面包体积失控的第一个隐患。一个全量字体文件通常有 150KB 到 300KB你可能实际用到的不到二十个图标剩下一大半都是无效载荷。把没用的字符编码从字体里剔除文件大小可能直接从 200KB 降到 10KB 左右。这个差异在小程序 2MB 主包限制下完全是两个概念。所以从 pick 图标开始就应该严格按设计稿里的实际清单来先整理一份“用到的图标名字列表”再到平台里一个一个添加。图标多的时候可以在项目里建分组按业务模块区分方便后续维护。2.2 下载包里哪些文件真正有用在 iconfont 平台选择 Font class 方式下载得到的包里有demo.css、demo_index.html、iconfont.css以及一堆字体文件比如iconfont.eoticonfont.svgiconfont.ttficonfont.wofficonfont.woff2这些文件不是全都有用。.eot是给老版本 IE 用的.svg是给早期 iOS 用的现代场景下基本可以无视。微信小程序端最稳的是.ttf部分基础库对.woff的兼容性在不同安卓机型上表现不一为了避免玄学问题我一般只保留.ttf并在 CSS 的src里也只保留truetype这一条。如果你发现下载包里没有.ttf可以在 iconfont 平台的项目设置里调整“字体格式”选项确保勾选了 TTF。2.3 把字体文件安排进 uniapp 工程推荐的项目目录结构是单独建一个目录比如common/iconfont里面放iconfont.css和iconfont.ttfsrc/common/iconfont/ ├── iconfont.css └── iconfont.ttf然后把这个 css 全局引入。uniapp 项目里最稳妥的做法是在App.vue的style里引入因为App.vue的样式默认是全局生效不会被scoped限制style import ./common/iconfont/iconfont.css; /style这里有个容易被忽略的坑如果你把import放到某个页面的style scoped里编译后字体文件的相对路径可能会基于当前页面目录去解析导致在真机上找不到字体文件。局部页面的图标正常其他页面的图标全是方块。所以 iconfont 的全局样式就老老实实放在App.vue的全局 style 里。3. 微信小程序的字体加载机制与路径问题3.1 为什么 H5 里好好的相对路径到小程序里就失效很多人的第一版做法是把 iconfont 下载包里的 css 原封不动拿过来里面src写的是相对路径font-face { font-family: iconfont; src: url(iconfont.ttf?t123456) format(truetype); }这套写法在 H5 页面里完全没问题浏览器会顺着相对路径去请求字体文件。但微信小程序不是浏览器它的 WXSS 对 CSS 里 URL 资源的处理能力非常弱。uniapp 编译器不会像 webpack 处理图片那样把这个url()里的字体文件自动打包成一个可用的资源引用。结果是开发工具里因为本地文件能直接读取看起来是正常的等到了真机上小程序环境根本不知道这个相对路径对应哪个资源字体自然加载失败图标就退化成一个个方框或者干脆什么都不显示。3.2 三套可用方案base64 内嵌、网络地址、loadFontFace针对这个限制我从项目实践里总结出三种比较靠谱的姿势。第一套把字体文件转成 base64 内嵌到 CSS 里这是最省心、也最稳的方案不依赖外部域名不受微信小程序合法域名校验的限制。做法很简单把.ttf文件转成 base64 字符串然后拼到src里font-face { font-family: iconfont; src: url(data:font/truetype;charsetutf-8;base64,AAEAAAA...) format(truetype); }在终端里可以先转出 base64 文本base64 -i iconfont.ttf -o iconfont_base64.txt然后把内容替换进iconfont.css。这种方案的缺点很直白base64 会让字体文件体积膨胀大约 33%而且全部写进 CSS 后这个 css 文件本身会变大不少。但它换来的是一劳永逸的稳定性特别适合一个项目里图标种类有限、变化不频繁的场景。第二套把字体放到 CDN使用网络地址加载如果你对体积非常敏感可以考虑把iconfont.ttf传到自己的 CDN然后 CSS 里写完整 HTTPS 地址font-face { font-family: iconfont; src: url(https://your-cdn.example.com/fonts/iconfont.ttf) format(truetype); }但微信小程序对网络资源有严格校验。字体文件请求会被认为是下载类请求需要在小程序公众平台后台的“开发管理-服务器域名”里配置 downloadFile 合法域名。如果只是本地调试要在微信开发者工具的“详情-本地设置”里勾选“不校验合法域名、web-view业务域名、TLS 版本以及 HTTPS 证书”。我记得很久之前有个项目忘记配这个域名结果图标只在开发工具里显示真机上一片空白排查了半天才发现是域名校验的问题。第三套用 wx.loadFontFace 动态加载微信小程序官方提供了wx.loadFontFace接口可以在运行时加载网络字体。这个 API 的好处是加载时机可控、页面切换时不阻塞渲染适合字体文件较大、只在个别页面用到的场景。但它同样走网络请求域名校验问题绕不开而且加载是异步的首次渲染时图标会出现短暂空白闪烁。我在项目里只在“某个独立活动页必须用一个特殊字体”时用过普通的 iconfont 集成不推荐优先考虑它。3.3 打包体积临界点base64 膨胀与 2MB 主包限制uniapp 编译微信小程序时主包体积限制是 2MB。网上经常看到有人报错source size 2612kb exceed max limit 2mb这种问题很多时候就是 iconfont 的 base64 体积惹的祸。计算一下如果一个全量 iconfont 字体文件是 250KB转成 base64 后大约是 333KB。这还只是一个字体文件。如果项目中再有一些引用的本地图片、公共 js 库很容易逼近体积红线。控制体积的几个关键手段按优先级我建议这样做从源头收紧下载图标时只挑实际使用的这比任何后端压缩都管用因为我见过一百个图标的字体文件压缩到只剩 15KB 后效果依旧完美。使用字体子集化工具如果已经下载了全量字体文件可以用font-spider这类工具分析出真正被content引用的字符生成只有这些字符的新字体文件npx font-spider ./index.html前提是你准备一个包含所有图标类名的临时 HTML 文件让工具去抓取。把不常用的页面拆成微信小程序分包如果你用的是 base64 方案且图标数量较多可以把一部份图标的 CSS 从App.vue挪到对应的分包页面里这样至少不会把所有体积都堆进主包。但要注意同一样字体被复制到多个分包总包体积未必划算操作前先算一笔账。最后才考虑网络字体方案网络字体不占用本地包体积但要接受字体加载延迟和域名配置成本。如果项目对首次渲染要求很高需要配合骨架屏或者按需加载去优化体验。4. 封装 Icon 组件日常开发中最高频的几类用法4.1 一个基础 Icon 组件应该长什么样直接在页面模板里写text classiconfont icon-home不是不行但时间久了你会发现每个页面都要关心前缀、样式、事件代码十分零散。我习惯封装一个Icon组件把细节收敛起来。template text classiconfont :classicon- name :style{ fontSize: realSize, color: color } click$emit(click, $event) /text /template script export default { name: AppIcon, props: { name: { type: String, required: true }, size: { type: Number, default: 32 }, color: { type: String, default: } }, computed: { realSize() { return this.size rpx } } } /script这里有两个细节值得注意微信小程序里的text组件和 HTML 的i标签行为不完全一样它的默认font-size在某些机型上会被重置。所以封装组件时最好不要依赖继承字号显式设置fontSize是最稳妥的。颜色同样要显式传不加color时字号可以继承颜色却未必符合预期尤其当页面里其他元素有独立文字颜色时。4.2 动态图标、循环渲染和状态切换的写法项目里最常遇到的不是静态图标而是动态图标。比如列表数据里每个 item 的图标名来自接口或者点击按钮后图标要在“展开/收起”之间切换。动态绑定的写法注意别漏掉iconfont这个基础类AppIcon :nameitem.iconName :size28 color#333 /如果你是在v-for里使用且图标名来自接口字段我建议使用数组形式绑定类名避免字符串拼接可能带来的前后空格问题text :class[iconfont, icon- item.iconName]/text状态切换的时候常见做法是计算属性里根据条件返回不同的 namecomputed: { iconName() { return this.expanded ? fold : unfold } }这种方式比在模板里写一堆v-if分支清晰得多后续要加第三种状态时也只改一处计算逻辑。4.3 tabBar、多色图标等边角问题老实说字体图标并不是万能的。微信小程序的原生 tabBar 只支持图片格式iconPath必须是本地 png/jpg 路径网络图片、base64 图片都不行。所以 tabBar 里的图标基本还是要走切图路线。如果你特别想用字体图标方案只能通过自定义 tabBar 组件实现但需要自己处理页面切换、选中状态、安全区适配这些细节成本并不低。我的项目里是直接让设计导出 png 的。另一个问题是多色图标。font class 方式渲染的图标颜色完全由 CSS 的color控制所以它本质上是单色图标。iconfont 平台里很多精美图标是多色的这类图标如果坚持用字体方案会发现颜色永远不对。处理方式有几种找同图形的单色版本或者把多色图标单独截成小图。不要把多色图标强行塞进 font class 里我试过一次最后不得不重新走图片方案白折腾一轮。5. 一次真实的白屏排查开发工具正常、真机不显示5.1 从“显示方块”到锁定字体加载失败我印象最深的一次是项目已经准备提测了同事突然跑过来告诉我“首页图标在安卓真机上全是方块”。开发工具里看是完全正常的预览二维码扫出来却不正常。遇到这种问题第一件事不是改代码而是确认现象的真实原因。我当时按这三步走打开微信开发者工具的“真机调试”把页面跑起来看 console 里有没有字体加载失败的报错。在开发者工具的 Sources 面板里检查一下iconfont.css是不是真的被编译进去了字体文件有没有作为一个资源被打包。在页面样式里搜索font-face确认它声明的src在真机环境下还能不能访问。最终问题定位得很清晰CSS 里的src是相对路径url(iconfont.ttf)H5 端能正常加载但小程序真机上找不到对应文件整个font-face声明就形同虚设图标自然全部塌方成方块。5.2 修复过程相对路径换成 base64步骤全记录决定用 base64 方案后我操作的完整过程是这样第一步先备份原来的iconfont.css避免改一半想回退找不到原文件。第二步把字体文件转成 base64base64 -i iconfont.ttf -o iconfont_base64.txt第三步打开生成的文件把整段 base64 字符串复制出来替换掉iconfont.css里的srcfont-face { font-family: iconfont; src: url(data:font/truetype;charsetutf-8;base64,AAEAAAA...) format(truetype); }第四步删掉工程里对原iconfont.ttf的引用避免 HBuilderX 打包时仍然把字体文件误塞进包里占体积。第五步微信开发者工具里清一次缓存“工具-清除缓存-全部清除”然后重新编译、真机预览。这里我说一个特别实际的排查点改了 CSS 之后开发工具如果还在用旧缓存页面显示正常很容易让人误以为已经修复完成。但实际上真机可能还是旧代码。所以提交前一定要清缓存、重新预览最好换一台之前没连着开发工具的测试机扫码验证。5.3 预防复发工程层面的几个固定习惯这个坑踩过一次之后我后续所有 uniapp 小程序项目都固定了几个习惯iconfont 的 CSS 永远放在App.vue全局样式里不放进单个页面的 scoped 样式。字体文件进工程之前先检查src是不是 base64如果是相对路径当场处理不等到真机出问题再补。下载图标时只选实际使用的并把图标分组管理这样即便以后要生成新字体文件改动范围可控。每次改完 iconfont 相关文件都走一遍“清缓存-重新编译-真机预览”三步这不是矫情是真机环境才有最终发言权。平时开发时真机上出现图标问题的概率并不高但一旦出了排查成本往往远高于从一开始就采用稳妥方案的代价。我在实际项目里还有一个小技巧如果一个页面有大量动态图标且图标数量经常变动可以在接口数据里直接返回图标名字前端只维护一套映射。这样即使后续图标更换也不会牵扯到样式文件只要 iconfont 平台侧重新生成了对应的字符编码更新 CSS 声明即可。这样的工作方式在交付给别的同事接手时也能减少很多沟通成本。