1. 为什么SSD1306显示中文总翻车
1.1 从一次“点不亮”的现场说起
前阵子帮朋友调一块0.96寸的OLED模块，I2C接口，SSD1306驱动芯片，接上Arduino Uno之后英文数字显示得好好的，一换成中文就满屏方块或者干脆花屏。他第一反应是“屏幕坏了”，又买了两块新的，结果一样。这个场景我见过太多次了，问题根本不在硬件，而在于字库和取模方式这两个环节。
SSD1306本身只是一块128×64像素的单色点阵屏，它不认识任何字符，更不认识汉字。你给它什么像素数据，它就老老实实点亮对应的点。英文能显示，是因为Adafruit_SSD1306或U8g2这类库内置了ASCII字库，把字母转成了点阵数据。中文没有内置字库，必须自己生成点阵数组，再通过代码写进屏幕的GDDRAM里。所以“显示不出中文”这件事，本质上是你没有把汉字的点阵数据喂给它，或者喂进去的格式和库的读取方式对不上。
这篇文章就是把这个完整链路拆开讲清楚：从取模软件怎么设置、生成什么格式的数组、代码里怎么调用、到常见花屏和乱码怎么排查。适合刚接触Arduino和OLED、想在项目里显示中文的玩家，也适合做过英文显示但一碰中文就卡住的开发者。
1.2 核心关键词先对齐
在动手之前，先把几个概念对齐，不然后面全是坑。
- SSD1306：OLED模块常用的驱动IC，支持I2C和SPI两种接口，分辨率常见128×64和128×32。
- 取模：把汉字或图形转换成点阵数据的过程，工具叫取模软件，比如PCtoLCD2002、字模提取软件等。
- 点阵字库：每个汉字用一组十六进制数表示，常见12×12、16×16、24×24等字号。
- GDDRAM：SSD1306内部的显存，128×64分辨率对应1024字节，每一位对应一个像素。
- 页地址模式：SSD1306的寻址方式之一，按页（8行像素为一页）写入数据，这也是取模时“纵向取模、字节倒序”这类选项的由来。
理解这几个词之后，你会发现整个流程就是：取模软件生成数组 → 代码里定义数组 → 调用显示函数把数组写进GDDRAM → 屏幕点亮对应像素。任何一环出错，中文就显示不出来。
2. 取模软件到底怎么设置才不出乱码
2.1 取模软件的选型与基本逻辑
市面上取模软件不少，PCtoLCD2002是最经典的一个，免费、体积小、支持自定义字号和取模方式。也有人用“字模提取V2.1”或者在线取模工具。工具本身差别不大，关键是输出格式必须和你的显示库匹配。
我个人的习惯是：如果用的是Adafruit_SSD1306库，取模时选“纵向取模、字节倒序”；如果用U8g2库，它自带中文支持，可以直接用U8g2的字体工具生成，或者用取模软件生成后按U8g2的格式调用。两种路线后面都会讲。
先讲通用路线，也就是自己取模、自己写显示函数，这条路线最锻炼理解，也最容易排查问题。
2.2 PCtoLCD2002的关键参数逐项拆解
打开PCtoLCD2002，点“模式”菜单，选择“字符模式”，然后点“选项”进入设置。这里每一项都直接影响最终数组能不能正确显示。
点阵格式：选“阴码”。阴码表示1代表点亮，0代表熄灭，这是绝大多数OLED库的约定。如果选阳码，显示出来就是反的，该亮的不亮，该灭的亮。
取模方式：选“纵向取模”。SSD1306的GDDRAM是按页组织的，每一页8行像素，纵向取模正好对应这种结构。如果选横向取模，写进去的数据会错位，显示出来就是乱码或者只显示一半。
取模走向：选“逆向（低位在前）”。这个选项和I2C传输时的位序有关，选错了字会左右镜像或者上下颠倒。实测下来，Adafruit_SSD1306库配合“逆向”是稳的。
输出数制：选“十六进制”。C语言数组用十六进制最方便，也最直观。
自定义格式：勾选“C51格式”，这样生成的数组直接就是{0x00,0x01,...}的形式，复制到Arduino代码里就能用。如果不勾选，生成的是纯十六进制文本，还得自己加括号和逗号，容易出错。
设置完之后，在输入框里打上你要显示的汉字，比如“你好”，选择16×16字号，点“生成字模”，下面就会出来一串十六进制数据。每个16×16汉字占32字节，两个汉字就是64字节。
2.3 取模时的三个隐藏坑
第一个坑是字号选择。0.96寸OLED分辨率128×64，16×16的汉字一行最多显示8个，一共4行。如果你选24×24，一行只能显示5个，而且取模数据量翻倍，Arduino Uno的SRAM只有2KB，存不了太多汉字。我一般建议16×16够用，需要大字号就用显示函数做缩放，或者换128×128的屏。
第二个坑是中英文混排。取模软件生成的是纯汉字点阵，英文和数字还是得靠库自带的ASCII字库。混排的时候要自己计算光标位置，汉字占16像素宽，英文占8像素宽，算错了就会重叠或者留空。
第三个坑是取模软件的编码。有些取模软件默认GB2312编码，如果你在代码里用UTF-8保存，数组本身没问题，但如果你是用字符串索引的方式去查字库，编码不一致就会找不到对应汉字。我的做法是直接把生成的数组硬编码到代码里，不依赖运行时编码转换，最稳。
3. 代码实现：从数组到屏幕的完整链路
3.1 硬件接线与库的安装
先确认硬件。0.96寸OLED模块一般有4个引脚：VCC、GND、SCL、SDA。接Arduino Uno的时候，VCC接3.3V或5V（看模块说明，大多数支持3.3V到5V），GND接GND，SCL接A5，SDA接A4。这是Uno的I2C默认引脚，别接错。
库的安装有两种路线。路线一是Adafruit_SSD1306加Adafruit_GFX，在Arduino IDE的库管理器里搜这两个名字，直接安装。路线二是U8g2，功能更强，自带中文支持，但学习曲线稍陡。我建议新手先走路线一，理解底层之后再换U8g2。
安装完Adafruit_SSD1306之后，先跑一个英文显示的例子，确认屏幕和接线没问题。例子在File → Examples → Adafruit SSD1306 → ssd1306_128x64_i2c。如果能正常显示，说明硬件链路通了，接下来只处理中文数据。
3.2 定义汉字点阵数组
假设我们用PCtoLCD2002生成了“你好”两个字的16×16点阵，得到64字节数据。在代码里这样定义：
const unsigned char hanzi_ni_hao[] PROGMEM = { 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, // 这里填入取模软件生成的64字节数据 };注意PROGMEM关键字，它把数组存到Flash里，不占SRAM。Arduino Uno的SRAM只有2KB，如果不用PROGMEM，存几个汉字就把内存吃满了，程序会跑飞。用了PROGMEM之后，读取的时候要用pgm_read_byte()函数，不能直接索引。
如果你用的是ESP32或ESP8266，SRAM大得多，可以不用PROGMEM，直接定义const unsigned char数组就行。但养成用PROGMEM的习惯没坏处，代码移植到小内存板子上不用改。
3.3 写一个通用的汉字显示函数
Adafruit_SSD1306库没有直接显示自定义点阵的函数，但提供了drawPixel()，我们可以基于它写一个。核心逻辑是：遍历点阵数组的每一位，如果是1就在对应位置画点。
void drawHanzi(int x, int y, const unsigned char *hz, int w, int h) { int byteWidth = (w + 7) / 8; for (int j = 0; j < h; j++) { for (int i = 0; i < w; i++) { int byteIndex = j * byteWidth + i / 8; int bitIndex = 7 - (i % 8); unsigned char b = pgm_read_byte(&hz[byteIndex]); if (b & (1 << bitIndex)) { display.drawPixel(x + i, y + j, SSD1306_WHITE); } } } }这个函数里，byteWidth是每行占用的字节数，16像素宽就是2字节。bitIndex的计算和取模时的“低位在前”对应，如果显示出来是镜像的，把7 - (i % 8)改成i % 8试试。pgm_read_byte是PROGMEM数组的读取方式，如果你没用PROGMEM，直接写hz[byteIndex]就行。
调用的时候：
display.clearDisplay(); drawHanzi(0, 0, hanzi_ni_hao, 16, 16); drawHanzi(16, 0, hanzi_ni_hao + 32, 16, 16); display.display();hanzi_ni_hao + 32表示跳过第一个字的32字节，指向第二个字的起始位置。这样两个汉字就并排显示出来了。
3.4 用U8g2库的另一种思路
如果你不想自己写显示函数，U8g2库是更好的选择。它内置了中文支持，可以用u8g2_font_wqy12_t_chinese1这类字体，直接调用drawUTF8()就能显示中文。缺点是字体文件占Flash空间，一个中文字体动辄几十KB，Arduino Uno的32KB Flash可能装不下。ESP32就没问题。
U8g2的取模工具叫u8g2_fonteditor，可以自己生成指定汉字的字体文件，只包含项目里用到的字，这样Flash占用就小很多。生成之后把字体文件放到Arduino库目录下，代码里引用就行。这条路线适合汉字数量固定、不想手动管理数组的场景。
4. 常见问题排查与避坑实录
4.1 显示方块、乱码、花屏的对照表
| 现象 | 最可能的原因 | 排查方法 |
|---|---|---|
| 满屏方块 | 取模方式选错，横向取模写成纵向 | 重新取模，选纵向取模、字节倒序 |
| 显示一半或错位 | 字号和显示函数参数不匹配 | 确认w和h与取模时一致 |
| 字左右镜像 | 取模走向选反 | 改“逆向”为“正向”或反之 |
| 字上下颠倒 | 页地址写入顺序反了 | 检查drawPixel的y坐标计算 |
| 只显示第一个字 | 数组偏移量算错 | 每个16×16字占32字节，偏移量按32递增 |
| 屏幕完全不亮 | 接线或I2C地址错 | 跑英文例子确认硬件，扫描I2C地址 |
| 显示几个字后程序重启 | SRAM溢出 | 数组加PROGMEM，减少全局变量 |
这张表是我自己踩坑总结的，基本上覆盖了90%的中文显示问题。遇到问题先对照这张表，比盲目改代码快得多。
4.2 三个只有实操才会遇到的坑
坑一：I2C地址不是0x3C。大多数0.96寸OLED的I2C地址是0x3C，但也有0x3D的。如果英文例子跑不起来，先跑一个I2C扫描程序，确认地址。Adafruit_SSD1306的构造函数里要填对地址，填错了屏幕没反应。
坑二：取模软件生成的数组多了花括号。PCtoLCD2002生成的C51格式有时候会带{和}，复制到代码里如果没删干净，编译会报错。我的习惯是生成之后先粘到记事本里，手动整理成纯十六进制加逗号的形式，再粘进代码。
坑三：display.display()忘了调用。Adafruit_SSD1306的绘制操作是先写到内存缓冲区，调用display.display()才真正刷到屏幕。新手经常画完点就以为完事了，结果屏幕没变化。这个坑我见过太多次，每次都要提醒。
4.3 性能与内存的平衡技巧
Arduino Uno的2KB SRAM是硬约束。一个16×16汉字32字节，存50个汉字就是1600字节，再加上Adafruit_SSD1306的缓冲区1024字节，直接爆了。所以必须用PROGMEM把字库放到Flash里，SRAM只保留屏幕缓冲区和少量变量。
如果汉字数量很多，比如要做菜单或者歌词显示，建议换ESP32或ESP8266，SRAM几十KB起步，Flash几MB，随便存。或者用U8g2的按需取模，只加载当前要显示的字，用完就释放。
另外，刷新率也要注意。I2C的默认速率是100kHz，刷一整屏128×64需要不少时间。如果做动画，把I2C速率提到400kHz，在Wire.begin()之后调用Wire.setClock(400000)，流畅度会明显提升。
5. 进阶玩法：从静态汉字到动态效果
5.1 汉字滚动显示的实现
静态显示搞定之后，滚动显示是下一个自然需求。思路很简单：把要显示的汉字串成一个长数组，每次刷新时改变起始偏移量，配合display.clearDisplay()和display.display()，就能实现左移、右移或者上下滚动。
具体做法是维护一个offset变量，每帧加1，绘制的时候从offset位置开始取点阵数据。当offset超过总宽度时归零。帧率控制在30fps左右，太高了I2C带宽不够，会闪烁。
这里有个细节：滚动的时候不要每个像素都重绘整个屏幕，只重绘变化区域。Adafruit_SSD1306没有局部刷新接口，但你可以自己算好脏矩形，只调用drawPixel画变化的部分，然后display()全屏刷。实测下来，128×64全屏刷在400kHz I2C下大概20ms一帧，够用。
5.2 中英文混排的对齐问题
中英文混排最麻烦的是宽度不一致。汉字16像素，英文8像素，如果按固定步长移动光标，英文之间会显得很空。我的做法是写一个drawStringMixed()函数，遇到ASCII字符就宽度加8，遇到汉字就宽度加16，光标位置动态计算。
判断是不是汉字，简单的方法是看字符编码。GB2312里汉字两个字节都大于0xA0，UTF-8里汉字三个字节且首字节大于0xE0。Arduino里字符串默认是UTF-8，所以判断首字节就行。不过更稳的做法是直接把要显示的文本和对应的点阵数组一起硬编码，不依赖运行时判断，省事又可靠。
5.3 用取模软件做简单动画
取模软件不仅能取汉字，还能取图片。把一张64×64的黑白图片导入PCtoLCD2002，按同样的纵向取模、字节倒序设置，生成512字节的数组，用drawBitmap()或者自己写的绘制函数显示出来，就是一张静态图。多张图连续切换，就是动画。
做动画的时候，每张图占512字节，10帧就是5KB，Arduino Uno的Flash装得下，但SRAM肯定不够，必须用PROGMEM。播放的时候用pgm_read_byte逐字节读取，速度够快，肉眼看不到卡顿。
如果要做更复杂的动画，比如带透明或者灰度，SSD1306不支持灰度，只能做黑白二值。想要灰度就得换屏，或者用抖动算法模拟，那是另一个话题了。
6. 我个人的实操体会
这套流程我前后调过不下二十块OLED，从Uno到ESP32，从Adafruit库到U8g2，踩过的坑基本都写在上面了。最深的体会是：中文显示的核心不是代码，而是取模设置和数组管理。代码部分一旦写通，后面就是复制粘贴的事；取模设置如果错了，代码写得再漂亮也显示不出来。
另外，别小看PROGMEM。我见过太多人因为没加PROGMEM导致程序随机重启，查了半天以为是电源问题，其实是SRAM溢出。养成习惯，所有常量数组都加PROGMEM，读取用pgm_read_byte，能省掉大量莫名其妙的故障。
最后分享一个小技巧：取模的时候，先把所有要用的汉字整理成一个文本文件，一次性取完，生成一个大的字库数组。然后在代码里写一个查找函数，根据汉字在字库中的索引返回对应的点阵指针。这样比每个汉字单独定义一个数组清爽得多，也方便后续增删。字库索引可以用汉字本身作为key，也可以用序号，看项目需求。我一般用序号，简单直接，不依赖编码转换。
