LVGL 这套图形库在嵌入式圈子里火了好几年了但凡用过的人基本都会经历同一个坎英文数字显示得好好的一换成中文就满屏方块、乱码甚至直接白屏。我最早在 STM32F407 上跑 LVGL v7 的时候为了显示一句系统就绪前前后后折腾了整整两天翻遍了各种论坛帖子踩的坑一个比一个离谱。这篇笔记就把我在 LVGL 上处理中文字体、以及顺带把日文、韩文、泰文这类非拉丁语系文字的完整思路捋一遍从字库原理、字体转换、编码处理到实际工程里的取舍尽量讲透。不管你是刚把 LVGL 移植到 STM32、ESP32 上还是已经在用 FreeRTOS 跑多任务界面只要涉及到中文显示这篇内容应该都能帮你少走点弯路。1. 为什么 LVGL 显示中文会翻车从字库和编码说起1.1 内置字体只覆盖 ASCII中文根本不在里面LVGL 默认自带的字体比如lv_font_montserrat_14、lv_font_montserrat_16这些本质上只包含 ASCII 字符集也就是 0x20 到 0x7F 这一百来个字符。你写lv_label_set_text(label, Hello)没问题因为每个字符都能在字体表里找到对应的点阵数据。但一旦你写lv_label_set_text(label, 你好)LVGL 拿着这两个字的 Unicode 码点去字体表里查查不到结果就是显示成方块或者干脆什么都不显示。这里有个很多人一开始会误解的点LVGL 内部处理文本用的是 UTF-8 编码。也就是说你传进去的你好这个字符串在内存里其实是 6 个字节每个汉字 UTF-8 占 3 字节LVGL 会先把它解码成 Unicode 码点你是 U4F60好是 U597D然后拿码点去字体里查字形。所以问题的根源不在于编码而在于字体文件里压根没有这些码点对应的字形数据。1.2 字库的三种存在形式点阵、矢量、以及 LVGL 的转换产物嵌入式里说字库其实有好几种形态理解它们的区别对后面选型很关键。第一种是点阵字库最典型的就是 HZK16 这种。HZK16 是 16x16 点阵的汉字库每个汉字占 32 字节按区位码排列。这种字库体积小、渲染快但放大就糊而且只支持固定字号。早期 12864 带字库的液晶屏用的就是这类方案。第二种是矢量字库比如 TTF、OTF 格式。矢量字体的好处是任意字号都清晰但解析和渲染开销大在资源紧张的 MCU 上直接跑矢量渲染基本不现实。第三种就是LVGL 自己的字体格式。LVGL 不直接吃 TTF而是通过官方的字体转换工具把 TTF 里你需要的那些字符预先转换成 C 数组形式的点阵数据编译进固件。这个转换产物就是lv_font_t结构体里面包含了每个字形的位图、宽度、advance 等元信息。这是嵌入式场景下最实用的方案因为运行时不需要解析字体文件查表即用速度快、内存可控。1.3 UTF-8 与 Unicode 的关系别搞混了这里必须澄清一个高频混淆点。Unicode 是字符集给每个字符分配一个唯一码点比如中是 U4E2D。UTF-8 是编码方式规定这个码点在内存里怎么存成字节序列。中的 UTF-8 编码是E4 B8 AD三个字节。LVGL 的文本 API 接收的都是 UTF-8 字符串。你在代码里写中文编译器会按源文件编码把它存成 UTF-8 字节前提是你的源文件确实是 UTF-8 保存的这点后面会专门讲坑。LVGL 解码时按 UTF-8 规则还原出码点再去字体表查。所以整条链路是源文件 UTF-8 字节 → LVGL 解码成 Unicode 码点 → 字体表按码点查字形 → 渲染。任何一环出问题中文就显示不出来。2. 字体转换工具怎么选、怎么用2.1 官方在线转换器与离线工具的区别LVGL 官方提供了一个在线字体转换器网址在官网的 Font Converter 页面。你把 TTF 文件传上去选好字号、bpp、要包含的字符范围它生成一个 C 文件给你下载。这个方式最省事适合快速验证。但在线工具有几个硬伤一是字符范围不好精确控制如果你只想包含项目里用到的几百个字在线工具要么让你全选文件巨大要么让你手动粘贴字符列表麻烦二是网络依赖公司内网环境可能访问不了三是批量处理不方便项目里要生成好几种字号就得重复操作。所以我更推荐用离线工具。LVGL 官方仓库里有lv_font_conv这个 Node.js 写的命令行工具功能比在线版强得多。安装方式npm install -g lv_font_conv装好之后就能用命令行批量生成字体。比如生成一个 16px、包含常用汉字的字体lv_font_conv --font SourceHanSansSC-Regular.ttf \ --range 0x20-0x7F \ --symbols 系统就绪温度湿度报警设置返回 \ --size 16 --bpp 4 --format lvgl \ -o my_font_16.c这里的--range指定 ASCII 范围--symbols指定额外要包含的汉字--bpp是每个像素的位数后面细讲--format lvgl输出 LVGL 格式。2.2 bpp 参数1、2、4、8 到底选哪个bppbits per pixel决定了字形的灰度级数直接影响显示效果和体积。bpp灰度级单字体积16px 估算适用场景12 级黑白约 32 字节单色屏、追求极致体积24 级约 64 字节小字号、资源极紧张416 级约 128 字节大多数彩色屏的推荐值8256 级约 256 字节大字号、追求平滑边缘我的经验是彩色 TFT 屏一律用 4bpp这是效果和体积的最佳平衡点。1bpp 在彩色屏上边缘锯齿非常明显尤其是笔画多的字糊成一团。8bpp 相比 4bpp 提升有限但体积翻倍除非你要显示很大的标题字否则没必要。举个实际数字一个包含 3000 个常用汉字、ASCII 全集的 16px 4bpp 字体生成的 C 文件大概在 400KB 到 500KB 之间。如果你的 MCU Flash 只有 512KB这就很吃紧了得考虑裁剪字符集或者用外部 Flash。2.3 字符集裁剪只包含用得到的字这是控制字体体积最有效的手段。一个完整的 CJK 字符集有 2 万多个汉字全塞进去生成的字体文件能到好几 MB嵌入式根本放不下。实际项目里界面上的文字是有限的——按钮标签、菜单项、提示信息加起来可能就几百个不同的字。我的做法是先把界面上所有可能出现的文字整理成一个字符列表去重后作为--symbols参数传给转换工具。这样生成的字体可能只有几十 KB。但这里有个坑如果界面文字是动态的比如从传感器读数据拼接、或者用户输入你没法预先知道会用到哪些字。这种情况有两个应对策略一是预留一个较大的常用字集比如 GB2312 一级字库的 3755 个字覆盖日常用语的 99%二是用外部字库文件运行时按需读取这个后面单独讲。2.4 多字号的处理别偷懒用一个字号缩放LVGL 的字体是固定字号的你不能像 CSS 那样font-size: 20px就自动缩放。有人图省事只生成一个 24px 的字体然后在小地方也用这个结果就是文字挤在一起或者超出控件。正确做法是按 UI 设计稿的字号分别生成。一般一个界面会用到 2 到 3 种字号正文 14 或 16px标题 20 或 24px大标题 32px。每种字号单独生成一个 C 文件在代码里分别声明。LV_FONT_DECLARE(my_font_14); LV_FONT_DECLARE(my_font_20); LV_FONT_DECLARE(my_font_32);然后在样式里指定static lv_style_t style_title; lv_style_init(style_title); lv_style_set_text_font(style_title, my_font_20);3. 把字体集成进工程从 C 文件到屏幕显示3.1 生成文件的目录组织与编译配置转换工具生成的 C 文件我习惯放在工程的fonts/目录下和业务代码分开。文件名带上字号比如my_font_14.c、my_font_20.c一目了然。这些文件需要加入编译。如果你用的是 Makefile就在源文件列表里加上如果用 Keil 或 IAR就在工程里 Add Existing Files。注意别漏加漏了的话链接时会报undefined reference to my_font_14这个错误很典型。还有个细节生成的 C 文件里字体数据是const数组会被放到 Flash 的只读段。如果你的链接脚本没配置好可能会被放到 RAM 里那就悲剧了——几百 KB 的字体直接把 RAM 撑爆。检查方法是在 map 文件里看这些符号的地址应该在 Flash 地址范围内。3.2 在 label 上应用字体的完整代码假设你已经生成了my_font_20.c里面定义的字体变量名是my_font_20转换工具的-o参数决定文件名变量名默认和文件名一致也可以用--force-fast-kern-format等参数调整具体看工具版本。#include lvgl.h LV_FONT_DECLARE(my_font_20); void create_chinese_label(void) { lv_obj_t *label lv_label_create(lv_scr_act()); lv_label_set_text(label, 系统就绪); /* 方式一直接设置字体 */ lv_obj_set_style_text_font(label, my_font_20, 0); lv_obj_align(label, LV_ALIGN_CENTER, 0, 0); }如果你用的是 LVGL v8 及以上样式 API 是lv_obj_set_style_text_font。如果是 v7则是lv_obj_set_style_local_text_font参数多一个状态位。这个版本差异坑了不少人移植旧代码时要注意。3.3 全局默认字体一劳永逸还是埋雷LVGL 允许你设置全局默认字体这样所有控件不用单独指定就用这个字体lv_theme_t *theme lv_theme_default_init( lv_disp_get_default(), lv_palette_main(LV_PALETTE_BLUE), lv_palette_main(LV_PALETTE_RED), true, my_font_16 /* 默认字体 */ ); lv_disp_set_theme(lv_disp_get_default(), theme);这招看起来很爽但有个隐患全局字体必须包含所有控件可能用到的字符。比如 LVGL 内置的一些控件日历、键盘会用到特殊符号如果你的字体没包含那些地方就会显示方块。所以我的建议是全局字体用一个包含 ASCII 常用符号 常用汉字的大而全字体特殊控件再单独覆盖。4. 那些年踩过的编码坑源文件、编译器、串口一个都不能少4.1 源文件编码UTF-8 无 BOM 是底线这是最隐蔽的坑。你的 C 文件里写了中文如果文件保存成了 GBK 编码编译器按 GBK 解析存进二进制的字节序列就不是 UTF-8LVGL 解码时自然乱码。统一用 UTF-8 无 BOM 保存所有源文件。为什么强调无 BOM因为有些编译器尤其是老版本的 GCC 和某些 ARM 工具链遇到 BOM 头会报错或者产生奇怪的行为。Keil 的话在 Edit → Configuration → Encoding 里选 UTF-8 without BOM。VS Code 右下角点编码切换选 UTF-8。验证方法用十六进制编辑器打开源文件看开头有没有EF BB BF三个字节有就是带 BOM 了。4.2 编译器字符集选项GCC 的 -fexec-charset即使源文件是 UTF-8GCC 还有个-fexec-charset选项控制执行字符集。默认情况下 GCC 会把字符串字面量转成执行字符集如果这个选项被设成了别的编码中文又会乱。在 Makefile 里确保没有奇怪的 charset 设置或者显式指定CFLAGS -fexec-charsetUTF-8 -finput-charsetUTF-8-finput-charset告诉编译器源文件是什么编码-fexec-charset告诉它字符串字面量转成什么编码。两个都设成 UTF-8最稳妥。4.3 串口打印中文xshell 和终端的编码设置调试时经常要把中文通过串口打印出来看。这里有两端要配对MCU 端发的是 UTF-8 字节流PC 端终端也要按 UTF-8 解码。用 xshell 的话在会话属性 → 终端 → 编码里选 UTF-8。用 SecureCRT 类似。如果终端设成了 GBK而 MCU 发的是 UTF-8就会看到一堆乱码。还有个常见问题串口助手的十六进制显示模式。有时候你怀疑是编码问题切到 HEX 模式看原始字节中应该是E4 B8 AD如果看到的是D6 D0那就是 GBK 编码说明源文件或者编译器环节出了问题。4.4 一个完整的排查链路我遇到中文乱码时排查顺序是这样的看源文件编码十六进制确认是 UTF-8 无 BOM。看编译器选项确认-fexec-charsetUTF-8。看串口原始字节HEX 模式确认发出来的是 UTF-8。看终端编码确认终端按 UTF-8 解码。看字体文件确认字体里包含了目标字符的码点。这五步走下来99% 的乱码问题都能定位。剩下 1% 是 LVGL 版本 bug 或者字体转换工具的坑那就得查 issue 了。5. 多语言支持日文、韩文、泰文怎么搞5.1 Unicode 码点范围与字体覆盖LVGL 的字体机制是通用的只要字体文件里包含了对应语言的码点就能显示。各语言的 Unicode 范围大致如下语言Unicode 范围说明中文U4E00 - U9FFFCJK 统一表意文字基本区日文假名U3040 - U30FF平假名 片假名韩文UAC00 - UD7AF谚文音节泰文U0E00 - U0E7F泰文字符阿拉伯文U0600 - U06FF从右往左书写用lv_font_conv生成时把这些范围加到--range参数里就行。比如中日韩都要lv_font_conv --font NotoSansCJK-Regular.ttf \ --range 0x20-0x7F,0x4E00-0x9FFF,0x3040-0x30FF,0xAC00-0xD7AF \ --size 16 --bpp 4 --format lvgl \ -o cjk_font_16.c但注意范围越大字体文件越大。CJK 基本区有 2 万多个字全包含进去 16px 4bpp 大概 2MB 以上。所以实际项目里还是要裁剪。5.2 阿拉伯文和泰文的复杂排版问题这里要泼盆冷水LVGL 对复杂文本排版的支持有限。阿拉伯文是从右往左书写而且字符会根据位置变形词首、词中、词尾形态不同泰文有上下叠加的元音和声调符号。这些都需要复杂的排版引擎类似 HarfBuzz来处理。LVGL 本身不做这些变形它只是按码点顺序逐个渲染字形。所以如果你要显示阿拉伯文得自己预处理文本把字符替换成对应的变形形式再交给 LVGL。泰文的叠加符号如果字体设计得当LVGL 能勉强显示但位置可能不理想。我的建议是如果项目只需要显示静态的、预先处理好的多语言文本LVGL 够用如果需要动态输入和复杂排版考虑换方案或者做大量预处理工作。5.3 字体合并把多个字体拼成一个有时候你需要中文用一个字体英文用另一个比如英文用更好看的 Montserrat中文用思源黑体。LVGL 支持字体回退fallback机制主字体找不到某个字形时去 fallback 字体里找。lv_font_t *my_font my_font_16; my_font-fallback lv_font_montserrat_16;这样英文数字用 Montserrat 渲染中文自动回退到 my_font_16。不过 fallback 链太长会影响性能一般不超过两层。另一种做法是用转换工具直接合并lv_font_conv支持多个--font参数按顺序查找字形。这种方式生成的字体是单一的运行时没有回退开销但灵活性差一些。6. 进阶方案外部字库与运行时加载6.1 什么时候需要外部字库当你的字符集大到无法全部编译进固件时就得考虑外部字库。典型场景需要显示完整 CJK 字符集2 万 汉字支持用户输入任意文字比如记事本应用多语言切换每种语言字符集都很大外部字库一般存在 SPI Flash、SD 卡或者外部 eMMC 里运行时按需读取字形数据。6.2 基于文件系统的字库读取思路LVGL 本身不直接支持从文件读字体但你可以自己实现一个lv_font_t把get_glyph_dsc和get_glyph_bitmap这两个回调指向你自己的函数在函数里根据码点去外部存储查数据。大致思路是预先用工具把 TTF 转成自定义的二进制格式建立码点到数据偏移的索引表。索引表放内部 Flash体积小字形数据放外部 Flash。回调函数里先查索引表拿到偏移再从外部 Flash 读字形位图到缓冲区返回给 LVGL。这个方案实现起来有一定工作量但一旦跑通就能支持任意大的字符集。我在一个带 SD 卡的项目里用过类似方案把 2 万汉字的字库放 SD 卡索引表放内部 Flash效果不错。6.3 缓存策略别每次都读 Flash外部读取的瓶颈在 IO 速度。如果每次渲染都去读外部 Flash界面刷新会卡顿。所以必须加缓存。简单的做法是维护一个 LRU 缓存缓存最近用到的 N 个字形。N 取 128 到 256 通常够用因为一屏显示的文字数量有限而且很多字会重复出现比如的是这些高频字。缓存的数据结构可以用一个数组加一个访问计数每次命中就把计数加一满了就淘汰计数最小的。实现不复杂但能显著提升流畅度。7. 实测中的性能与体积权衡7.1 字体体积对 Flash 占用的实测数据我在 STM32F4071MB Flash上做过一组实测用思源黑体生成不同配置的字体配置字符数文件大小编译后占用16px 4bpp ASCII300 汉字约 400约 60KB约 62KB16px 4bpp ASCII3755 汉字约 3850约 480KB约 490KB20px 4bpp ASCII300 汉字约 400约 90KB约 92KB16px 1bpp ASCII3755 汉字约 3850约 130KB约 135KB可以看到bpp 从 4 降到 1体积能省 70% 以上但显示效果牺牲很大。字符数从 300 增到 3755体积涨了 8 倍。所以裁剪字符集是性价比最高的优化手段。7.2 渲染速度4bpp 和 1bpp 的差异渲染速度方面1bpp 因为数据量小理论上更快但在实际测试中差异不明显因为瓶颈通常在 SPI 刷屏而不是字体解码。我用 16px 4bpp 字体在一个 320x240 的屏上刷新整屏文字帧率能到 30fps 以上完全够用。真正影响性能的是字体回退链和外部字库读取。回退链每多一层找不到字形时的查找开销就翻倍。外部字库如果没缓存每次读 SPI Flash 要几十微秒一屏几十个字就是几毫秒累积起来就卡了。7.3 一个真实的优化案例有个项目界面上有个实时刷新的数据列表每行显示温度25.3℃这样的文字。最初用的是 3755 汉字的完整字体Flash 占了 480KB而且刷新时有点卡。优化过程裁剪字符集把界面上所有文字整理出来去重后只有 180 多个不同的字重新生成字体后体积降到 40KB。分离数字字体数字和符号用单独的 1bpp 小字体进一步减小体积。加渲染缓存LVGL 本身有LV_IMG_CACHE_DEF_SIZE类似的机制但字体没有内置缓存我手动加了一层字形缓存。优化后 Flash 占用降到 50KB 左右刷新也流畅了。这个案例说明大部分项目根本不需要完整字库裁剪才是王道。8. 几个容易被忽略的细节8.1 标点符号的全角半角问题中文标点。是全角的占两个英文字符宽度英文标点是半角的。如果你的字体只包含了半角标点中文标点就会显示成方块。生成字体时记得把全角标点范围U3000 - U303F也包含进去。还有个细节中英文混排时的间距。LVGL 默认不做字距调整中英文混在一起可能显得挤。可以在样式里设置letter_space和line_space微调。8.2 字体变量的命名冲突如果你生成了多个字体文件注意变量名别冲突。lv_font_conv默认用输出文件名作为变量名比如-o my_font_16.c生成的变量是my_font_16。如果两个文件重名链接时会报重复定义。养成好习惯文件名带字号和用途比如ui_font_16.c、title_font_32.c。8.3 LVGL 版本差异带来的 API 变化LVGL v7 到 v8 的字体相关 API 有不少变化v7lv_obj_set_style_local_text_font(obj, LV_LABEL_PART_MAIN, LV_STATE_DEFAULT, font)v8lv_obj_set_style_text_font(obj, font, 0)字体结构体本身也有变化v8 的lv_font_t多了些字段。所以用转换工具时要注意选对版本lv_font_conv有--lvgl-version之类的参数具体看工具文档生成对应版本的格式。移植旧代码时如果字体显示异常先检查版本是否匹配。8.4 模拟器与真机的差异在 PC 模拟器上跑 LVGL 时字体渲染用的是 PC 的渲染后端可能和真机的渲染有细微差异。比如模拟器上看着清晰的 4bpp 字体真机上因为屏幕像素密度不同可能显得糊。所以字体效果一定要在真机上验证别只在模拟器上看。另外模拟器上如果用了系统字体比如 SDL 的 TTF 渲染那和真机的 LVGL 字体机制完全不同不能作为参考。9. 我个人的一些经验总结折腾 LVGL 中文字体这些年最大的体会是大部分问题都出在编码链路的某一环而不是 LVGL 本身。源文件编码、编译器选项、终端编码、字体字符集这四个地方任何一个不对中文就显示不出来。排查时按链路一步步来别跳步。另一个体会是字体体积控制要趁早。项目初期就规划好字符集别等到 Flash 快满了才想起来裁剪。我见过太多项目因为字体占了太多 Flash最后不得不砍功能或者换芯片。还有多语言项目要提前考虑字体方案。如果确定要支持中日韩一开始就选一个覆盖范围广的字体比如思源黑体、Noto Sans CJK别用只支持中文的字体后面加日文韩文时又得重来。最后分享一个小技巧用 Python 脚本自动提取源码里的中文字符。项目大了之后手动整理字符列表不现实。写个脚本扫描所有.c和.h文件用正则把中文字符提取出来去重输出成--symbols参数需要的格式。这个脚本我每个项目都会用省了大量手工劳动。import re import glob chars set() for f in glob.glob(src/**/*.c, recursiveTrue) glob.glob(src/**/*.h, recursiveTrue): with open(f, encodingutf-8) as fp: content fp.read() # 匹配所有非 ASCII 字符 for ch in content: if ord(ch) 0x7F: chars.add(ch) print(.join(sorted(chars)))把输出粘贴到lv_font_conv的--symbols参数里就能生成刚好覆盖项目需求的字体一个多余的字符都不带。这个习惯帮我省下的 Flash 空间累计起来相当可观。
