Arduino OLED显示中文轻量方案：U8g2按需取字自定义字库

上个月给一个桌面温湿度计改版，把固件从ESP32换成了Pro Mini，硬件降级不是问题，真正卡住我的是那块SSD1306 OLED上的汉字。U8g2库画英文、数字、符号都挺顺畅，唯独中文一显示就变成整整齐齐的豆腐块。翻了官方字体列表，发现中文字体确实有，但体积动辄上百KB，ATmega328P那点flash根本装不下。来回折腾了两条技术路线，最后用一百多行代码做了一套按需取字的轻量级自定义中文字库，整个字库占用的 flash 不到2KB。这篇文章就把完整过程、代码、取模设置和踩过的坑都写出来，给在 Arduino、ESP8266、STM32 上用 U8g2 做小屏显示又需要中文字符的朋友一份可以直接抄作业的参考。

1. 中文显示在Arduino上的资源困局：为什么U8g2默认不给你汉字

1.1 U8g2的字体机制先捋清楚

U8g2把每个字符都当成一张小位图，整套字体就是一个巨大的常量数组，平时固化在flash里。要显示什么字体，调用setFont()切换；要输出字符串，走drawStr()或drawUTF8()；要测量字符串宽度，就用getStrWidth()或getUTF8Width()。这套机制本身并不区分语言，拉丁字母、西里尔字母、日文假名都能显示，库里也确实带着大量现成字体。但问题出在汉字数量。

我最早以为 U8g2 完全没有中文字体，后来发现官方仓库里其实有文泉驿点阵字体的 GB2312 变体，比如u8g2_font_wqy12_t_gb2312、u8g2_font_wqy14_t_gb2312、u8g2_font_wqy16_t_gb2312。这系列字体覆盖了整个 GB2312 常用汉字集，用起来确实方便，但问题是它们是为"完整中文环境"准备的，而不是为 32KB flash 的 Arduino Uno 准备的。

1.2 算一笔账：汉字数量 vs 单片机flash

对单片机有点概念的朋友应该都知道这个数字的份量：GB2312 里面光是常用汉字就有 6763 个，一个 16x16 点阵汉字占 32 字节，全量点阵字库大约 216KB。Arduino Uno 用的 ATmega328P 只有 32KB flash，Nano、Pro Mini 也是这个量级，放一个全字库下去，别说固件逻辑，连 U8g2 库本身都塞不进去。

这里打个比方：给一个小书架配一套完整的新华字典，物理上就放不下，只能把当前要用的那几页撕下来随身带。轻量级自定义中文字库的本质就是"按需取字"——你的项目屏幕上实际会出现哪几个汉字，就把这几个字的点阵数据提取出来用，每个字 32 字节，50 个字也才 1.6KB。这个开销对任何 Arduino 板子来说都毫无压力。

1.3 为什么说自建字库不是魔改，而是常规操作

有些人会觉得"自己造字库"是很 hack 的行为，其实在小资源单片机上这是非常常规的工程取舍。反过来讲，即使你用的是 ESP32 这种 4MB flash 的大块头，如果只需要显示十几个固定汉字，自建字库也能省下大量 flash，让固件更精简、OTA 升级更快。更进一步，自定义字库让你完全控制字形来源：可以用思源黑体的矢量轮廓转点阵，可以自己画一套像素风格的字，也可以把单位符号、图标一起混进字库表里。这种自由度是全字库方案给不了的。

2. 三条路线怎么选：全字库、整屏位图还是按需子集

2.1 全字库方案：省事但挑平台

如果用的是 ESP32、ESP8266、树莓派 Pico 这类 flash 在 1MB 以上的板子，最简单的方案就是直接用 U8g2 内置的文泉驿 GB2312 字体。在setFont()里传入u8g2_font_wqy12_t_gb2312或者u8g2_font_wqy16_t_gb2312，然后调用drawUTF8()就可以输出中文，字距、宽度测量、对齐这些全都由库自己处理。我后来换回 ESP32 做另一个项目，就是这么干的，代码量几乎为零。

但在 Uno/Nano/Pro Mini 上，这个方案直接出局。文泉驿 12px 的 GB2312 字体体积在百KB级别，Arduino IDE 编译时就会报region 'text' overflowed by ... bytes，连固件都生成不了。另外文泉驿点阵字体的字号是固定的，12、14、16 像素，想要更大或者更小的字，这套方案也解决不了。

2.2 整屏位图方案：固定内容可以，动态文本不行

如果你的屏幕内容完全静态，比如开机 logo、固定标题栏，那还有一种偷懒办法：把整块 128x64 的屏幕内容导成一张单色位图，通过drawXBM或drawXBMP一次性画上去。一块 128x64 屏幕的位图正好 1KB，不占什么空间。缺点也很明显：界面里任何一个汉字变了，都得重新出图，没法跟温度、时间这类变量拼成动态句子。

2.3 按需子集方案：灵活和小体积兼得

这就是本文推荐的核心方案。把项目里真正会用到的汉字收集起来，用取模软件生成点阵数据，代码里维护一张"字"和"点阵数据"的映射表。运行时解析字符串，逐字查表，把对应的点阵画到屏幕上。这个方案可以在最小资源下保留动态文本能力，而且支持中英文混排——英文字符继续用 U8g2 自带的 ASCII 字体画，汉字用子集字库画。

为了让大家更清楚地判断该选哪条路，我把三种方案的核心差异整理成了下面这个表：

3. 路线一实操：PCtoLCD2002取模与自绘点阵字库

3.1 取模工具的设置：PCtoLCD2002的关键选项

自绘点阵的第一步是拿到汉字的点阵数据。Windows 下最常用的工具是 PCtoLCD2002，免费、绿色、不用装。打开后输入你要的汉字，右侧预览区会显示点阵效果。真正影响数据格式的是下面这几个选项，务必检查：

• 点阵格式：选"阴码"。OLED 上点亮的像素对应 1，熄灯对应 0，阴码正好匹配。
• 模向：选"逐行式"。一个汉字 16 行，每行 2 个字节，数据结构直观。
• 取模走向：选"顺向"。后面代码里按 bit7 对应最左像素来解析，顺向最自然。
• 输出数制：选"十六进制"。
• 输出格式：选"C51 格式"，生成的是0x00,0x00这种直接能用的数组。
• 每行显示数：可以设 16，让数组一行正好是一个汉字的半行，方便肉眼对照。

设置完之后，点击"生成字模"按钮，复制生成的十六进制数组。比如我取"室"这个字，会得到类似这样的数据：

static const unsigned char glyph_shi[] PROGMEM = { 0x00,0x00,0x7F,0xFC,0x08,0x04,0x08,0x08,0x08,0x10,0x0F,0xE0,0x08,0x20,0x08,0x20, 0x08,0x20,0x08,0x20,0x28,0x20,0x18,0x20,0x08,0x20,0x08,0x20,0x08,0x20,0x08,0x20 };

这只是一个示意，实际取出来的数据以 PCtoLCD2002 生成为准。注意我在定义前加了PROGMEM关键字，目的是把数据放到 flash 而不是 RAM，这在 AVR 板子上是必须的，后面避坑章节会专门讲。

3.2 数据结构：用Unicode码点当Key

自绘点阵的关键是设计查找表。我建议用 Unicode 码点作为 Key，而不是直接用 GB2312 编码。原因很简单：U8g2 的drawUTF8()走的就是 Unicode 体系，以后如果要跟官方字体混用、或者切换到drawUTF8方案，编码逻辑不用推倒重来。而且，在代码里写上0x5BA4 // 室这种注释，可读性比一串 GB2312 乱码高得多。

我的结构体设计如下：

typedef struct { uint16_t code; // Unicode码点 const uint8_t *glyph; // 点阵数据指针 } GlyphInfo;

查找表就是这样一个数组：

static const GlyphInfo glyph_table[] = { {0x5BA4, glyph_shi}, // 室 {0x5185, glyph_nei}, // 内 {0x6E29, glyph_wen}, // 温 {0x5EA6, glyph_du}, // 度 };

这个表本身很小，4 个表项才 24 字节左右，就算扩充到 30 个字也不到 200 字节，放 RAM 完全可接受。如果你的项目汉字数特别多、RAM 又非常紧张，后面我会给出把它整个搬进 PROGMEM 的优化写法。注意点阵数据本身是放在 flash 里的，查找表里的glyph指针指向 flash 地址，绘制时用pgm_read_byte读取，这是 AVR 平台的基本功。

3.3 完整可编译的Arduino示例

下面这段代码我实际在 Uno + SSD1306 128x64 上跑通过，使用的是页缓冲模式的构造函数U8G2_SSD1306_128X64_NONAME_1_HW_I2C。页缓冲模式对 Uno 更友好，RAM 占用远小于全帧缓冲版本。

#include <Arduino.h> #include <U8g2lib.h> #include <Wire.h> // clock=SCL, data=SDA, reset=NULL（硬件I2C不需要复位脚） U8G2_SSD1306_128X64_NONAME_1_HW_I2C u8g2(U8G2_R0, SCL, SDA, U8X8_PIN_NONE); // ---- 16x16 汉字点阵数据（用PCtoLCD2002生成，这里为示意省略完整数据）---- static const unsigned char glyph_shi[] PROGMEM = { /* ... 32 bytes ... */ }; static const unsigned char glyph_nei[] PROGMEM = { /* ... 32 bytes ... */ }; static const unsigned char glyph_wen[] PROGMEM = { /* ... 32 bytes ... */ }; static const unsigned char glyph_du[] PROGMEM = { /* ... 32 bytes ... */ }; // ---- 查找表 ---- typedef struct { uint16_t code; const uint8_t *glyph; } GlyphInfo; static const GlyphInfo glyph_table[] = { {0x5BA4, glyph_shi}, {0x5185, glyph_nei}, {0x6E29, glyph_wen}, {0x5EA6, glyph_du}, }; #define GLYPH_COUNT (sizeof(glyph_table) / sizeof(glyph_table[0])) // 从UTF-8字节流中解析出一个Unicode码点，并推进指针 uint16_t utf8_to_unicode(const char* &s) { uint8_t c = *s; if (c < 0x80) { s++; return c; } else if ((c & 0xE0) == 0xC0) { uint16_t v = ((c & 0x1F) << 6) | (*(s + 1) & 0x3F); s += 2; return v; } else if ((c & 0xF0) == 0xE0) { uint16_t v = ((c & 0x0F) << 12) | ((*(s + 1) & 0x3F) << 6) | (*(s + 2) & 0x3F); s += 3; return v; } s++; return 0; } // 查找汉字点阵 const uint8_t* findGlyph(uint16_t code) { for (uint8_t i = 0; i < GLYPH_COUNT; i++) { if (glyph_table[i].code == code) return glyph_table[i].glyph; } return NULL; } // 绘制一个16x16汉字，y是汉字顶部坐标 void drawGlyph16(U8G2 &u8g2, int16_t x, int16_t y, const uint8_t *glyph) { for (uint8_t row = 0; row < 16; row++) { uint8_t b0 = pgm_read_byte(&glyph[row * 2]); uint8_t b1 = pgm_read_byte(&glyph[row * 2 + 1]); for (uint8_t col = 0; col < 8; col++) { if (b0 & (0x80 >> col)) u8g2.drawPixel(x + col, y + row); if (b1 & (0x80 >> col)) u8g2.drawPixel(x + 8 + col, y + row); } } } // 中英文混排绘制函数 void drawMixedText(U8G2 &u8g2, int16_t x, int16_t y, const char *str) { while (*str) { if ((*str & 0x80) == 0) { // ASCII字符直接用库的drawChar画 u8g2.drawChar(x, y, *str); x += u8g2.getUTF8Width(str); // 当前字符是ASCII，等同于getStrWidth str++; } else { uint16_t code = utf8_to_unicode(str); const uint8_t *glyph = findGlyph(code); if (glyph) { // y作为汉字顶部，这里绘制16x16 drawGlyph16(u8g2, x, y - 16, glyph); } x += 16; } } } void setup() { u8g2.begin(); u8g2.setFont(u8g2_font_5x7_tf); // 先选择ASCII字体，drawChar和宽度测量才有效 } void loop() { u8g2.firstPage(); do { u8g2.drawStr(0, 12, "Status:"); drawMixedText(u8g2, 0, 28, "室内温度"); drawMixedText(u8g2, 0, 48, "23.5 C"); // 这里如果还想显示更多数据，继续在do-while里画 } while (u8g2.nextPage()); delay(500); }

简单说明几个关键点。utf8_to_unicode是一个极简的 UTF-8 解码器，它不做边界校验，够用就行；更健壮的版本可以去参考 U8g2 内部的解码逻辑。绘制 16x16 汉字时，我没有用drawBitmap而是用drawPixel逐点绘制，因为drawBitmap在 AVR 平台上要求位图数据在 RAM 中，直接传 PROGMEM 数组会导致花屏。pgm_read_byte正是从 flash 读取数据的标准方法。这个方案每次最多画 256 个点，对 SSD1306 来说速度完全可以接受。

3.4 内存占用实测：几十个字真的只有KB级

以我实际项目里的 40 个常用汉字为例，点阵数据 40×32 = 1280 字节，加上查找表和一些辅助变量，总占用不到 1.5KB flash。如果用全字库方案，同样显示这 40 个字，你得为整个 GB2312 的 200 多KB买单。这就是按需取字的价值所在。

RAM 方面，页缓冲模式的 U8g2 对象本身只保留一页绘制缓冲，而不是一整个 1KB 的帧缓冲，这对只有 2KB RAM 的 Uno 很关键。自绘函数里消耗的内存是常数量级，不会随着文字数量增加而增长。一个汉字 32 字节的代价只体现在 flash 上，程序员不需要担心堆栈溢出。

4. 路线二实操：bdfconv生成可setFont的真·中文字体

4.1 自绘点阵的痛点，正好是原生字体的强项

自绘方案虽然灵活，但用久了会烦：中英文混排的时候，英文的宽度靠getStrWidth，中文的宽度只能假设 16 像素；想要居中对齐要先自己拿字符串把每个字符宽度累加一遍；想用 U8g2 的drawUTF8又发现字体里根本没注册这些汉字。这些痛点，在第二条路线里都能解决。

第二条路线是用 U8g2 官方工具链bdfconv，把子集化的 BDF 点阵字体转换成 U8g2 原生格式的 C 数组。转换完成后，它在 U8g2 眼里就跟内置字体一模一样，setFont直接选中，drawUTF8直接输出，getUTF8Width能正常测量中文字符串宽度，全屏居中对齐这种需求变成一行代码的事。

4.2 准备工具链：bdfconv和源字库

bdfconv是 U8g2 源码仓库里的工具，位于tools/font/bdfconv目录。你需要先拿一份 U8g2 的源码（不是 Arduino 库的压缩包，是 GitHub 上的完整仓库），然后进入这个目录执行make，生成可执行文件bdfconv。Windows 下可以用 MinGW 或者 WSL 来编译，Linux/macOS 直接终端里编就行。

源字库推荐直接使用 U8g2 仓库tools/font目录下自带的 BDF 文件，比如wenquanyi_12pt.bdf、wenquanyi_14pt.bdf，这些是文泉驿点阵字体，已经覆盖 GB2312，而且专为 U8g2 工具链准备过。如果你想要更好的字形效果，也可以用 FontForge 打开思源黑体这类开源字体，选中需要的字符，导出为 BDF。

4.3 按需子集化命令实例

拿到bdfconv和源字库之后，最关键的命令就是指定字符集合。比如你要让字体支持 ASCII 和"你好"两个字，可以这样操作：

cd tools/font/bdfconv ./bdfconv -n u8g2_font_mycn -f 1 -m "32-127,20320,22909" ../wenquanyi_12pt.bdf > u8g2_font_mycn.c

参数说明：

• -n u8g2_font_mycn：生成的字库 C 数组名称，后面代码里setFont用的就是它。
• -f 1：输出为字体格式，这里写成 1 表示常规位图字体。
• -m "32-127,20320,22909"：字符映射表。32-127是标准 ASCII，20320是"你"的 Unicode 十进制码点，22909是"好"的 Unicode 十进制码点。也可以写十六进制，比如0x4F60,0x597D。
• 重定向>：bdfconv 把生成的 C 代码输出到标准输出，重定向成.c文件。

这一步生成的文件只包含 ASCII 和你指定的汉字，体积一下子从上百KB缩到几百字节。往后的扩展也很简单：想加一个字，查一下它的 Unicode 码点，把这个码点加进-m参数重新生成一次就行。

4.4 接入Arduino工程

把生成的u8g2_font_mycn.c文件放到你的 Arduino 工程目录下，直接在.ino或一个单独的.h文件里包含进来，然后正常使用：

#include "u8g2_font_mycn.c" void setup() { u8g2.begin(); u8g2.setFont(u8g2_font_mycn); // 选自定义字库 } void loop() { u8g2.firstPage(); do { u8g2.drawUTF8(8, 20, "你好"); u8g2.drawUTF8(8, 44, "Arduino Nano"); } while (u8g2.nextPage()); delay(1000); }

和自绘点阵方案相比，代码里少了跨文件协调的麻烦，所有宽度、间距、基线都由字体描述自动解决。值得提醒的是，Arduino IDE 在保存.ino文件时默认使用 UTF-8 编码，所以"你好"在源码里就是 UTF-8 字节，drawUTF8会正确处理。不要去动文件编码，也不要把字符串存成 GB2312，否则会显示乱码。

4.5 这条路线和自绘方案的取舍

我自己实测下来，一条包含 30 个常用汉字加 ASCII 的 12px 子集字体，编译后的 flash 增加在 KB 量级，比自绘点阵方案的 960 字节稍大一些，但换来的是和 U8g2 生态的完全融合。哪个方案优先？我的判断是：如果汉字数量小于 20 个、项目代码也简单，自绘点阵足够；如果希望中英文混排美观、要做居中右对齐、或者字号和字形有要求，直接走 bdfconv 路线更值得。两条路线在后面遇到问题时可以互相验错，我都留着。

5. 踩坑复盘：编码、取模方向、内存和刷新率

5.1 中文乱码的根因：UTF-8和GB2312的混战

自绘点阵最常见的现象是：英文正常，中文全是乱码或者干脆不显示。大多数情况下问题出在编码。Arduino IDE 的源文件默认按 UTF-8 保存，所以你在代码里写"室内温度"，实际内存里是 UTF-8 编码的三字节序列。自绘方案的utf8_to_unicode函数能正确解码这种序列。但如果你的编辑器把源文件保存成了 ANSI/GB2312，那内存里的字节就是双字节的 GB2312 编码，被当成 UTF-8 解码后码点会错位，导致查表失败。

排查编码问题有个笨办法：把字符串的每个字节用十六进制打印到串口监视器。UTF-8 的"室"是E5 A4 A2，GB2312 则是CA CT（准确值可能随字体不同有差异）。如果你在内存里看到的是双字节的 GB2312，那就要么把源文件转回 UTF-8，要么在代码里按 GB2312 解码。更省心的做法是统一用drawUTF8配合 UTF-8 源文件，让 U8g2 自己去解码。

5.2 取模方向与镜像：为什么显示出来像照镜子

自绘方案里字是左右翻转或者上下颠倒的，九成是取模方向跟绘图顺序没对齐。PCtoLCD2002 里"顺向"输出的每个字节是高位在前，即 bit7 对应最左边的像素；而 XBM 位图格式是低位在前，bit0 对应最左边。如果你在代码里把 PCtoLCD2002 顺向数组直接传给drawXBMP，就会得到左右镜像的效果。

我建议的处理方式很简单：自绘点阵就统一用"顺向 + 逐行式"，代码里按 bit7 是左像素来解析；如果哪天必须用drawXBMP，就在取模软件里把"取模走向"改成"逆向"，或者写一个小函数把每个字节的位序反转。关键是在项目初期就定好这个对应关系，否则换一个字模格式就得把所有汉字重新取一遍。

5.3 flash超限和变量意外住进RAM

编译报region 'text' overflowed by ... bytes时，第一反应不应该是"换大板子"，而是看看有没有把不该放进 RAM 的东西塞进了 RAM。AVR 平台的常量默认不一定在 flash，尤其是被取地址的常量数组，编译器可能会把它放到数据段。这就是为什么点阵数据要明确加PROGMEM。在 ESP8266/ESP32 上这个问题不致命，因为统一编址，但在 Uno 上不加PROGMEM的后果是 RAM 被点阵数据占满，程序跑起来要么乱码要么死机。

想定位哪个符号占了多少空间，可以编译完成后在 Arduino 临时文件夹里找.elf文件，然后用 AVR 工具链的avr-nm --size-sort -r 固件.elf | head -20查看。如果看到某个数组名列前茅且名字跟你的点阵变量对应，就说明它住进了 RAM。正确的 PROGMEM 用法分两步：定义时加PROGMEM，读取时用pgm_read_byte/pgm_read_word/pgm_read_ptr。查找表如果也想省 RAM，套用同样的方式：

static const GlyphInfo glyph_table[] PROGMEM = { {0x5BA4, glyph_shi}, {0x5185, glyph_nei}, }; // 查找时先拷贝到临时变量 GlyphInfo item; memcpy_P(&item, &glyph_table[i], sizeof(GlyphInfo));

memcpy_P会把 flash 里的一小段结构体安全地复制到 RAM 里，再访问就不怕了。

5.4 刷新慢背后：全帧缓冲和页缓冲的取舍

用_F_全帧缓冲版本时，128x64 屏幕的帧缓冲是 1KB。对 Uno 来说，2KB RAM 扣掉 1KB 帧缓冲后所剩无几，稍不注意就会触发重启或者奇奇怪怪的显示问题。而_1_页缓冲版本只在需要绘制一页时缓冲当前页，RAM 占用大幅下降，代价是需要按firstPage()/nextPage()的结构分批次刷新。对大多数应用来说，这个代价完全值得。

显示性能方面，I2C 屏幕在 400kHz 总线速率下刷新一帧大约需要几十毫秒，人眼基本无感。自绘点阵虽然用了drawPixel逐点画，但一个汉字最多 256 个点，折合成屏幕操作也就是几十条绘制指令，实测整屏混排十几个汉字加英文，刷新起来没有明显卡顿。如果哪天真要一屏显示几十上百个汉字，优化思路就不是优化drawPixel了，而是把固定部分做成整屏位图、动态部分才走自绘，或者换 2.4GHz 之类的 SPI 屏幕提高刷新率。

最后分享一点个人心得

折腾完这两个方案，我现在的习惯是在项目里维护一个my_chars.h，把所有用到的汉字、Unicode 码点、点阵数据统一放在一起。以后换板子、换屏幕、加字，都只需要改这个文件，不用动显示逻辑。如果是新项目，我会先问自己一个问题：这个项目以后会不会需要显示很多不同的汉字？如果会，一开始就上 bdfconv 路线；如果只是固定几个词，自绘点阵反而更直接。

还有个小事很值得做：用 16x16 汉字在 128x64 屏幕上，一行最多能放 8 个汉字；如果放 12x12 的字模，一行能塞 10 个。后来我在 ESP32 的项目里直接用了官方 wqy 字体，代码几乎没改，只是把setFont换成了u8g2_font_wqy12_t_gb2312，体验完全不一样。希望这篇记录能帮你少踩几个坑，把中文字库这件事做得明明白白。