ESP32 小屏显示中文：字体、编码和字库大小怎么取舍 · ESP32 专栏

01 / 屏幕字体

中文显示要同时满足编码、字形与布局

YAML按UTF-8保存，UTF-8字节编码对应Unicode码点；字体提供码点形状，glyphs决定本次固件实际编入哪些字。编码正确而缺glyphs仍会显示不全，字都存在却坐标越界也会被裁切。

本例只显示固定合成“中文测试、温度23.5C、湿度45.0%”，23.5/45.0不是本站测量。先把字形链单独验收，再与后续真实传感器组合；本地显示不要求连接HA。

接线图字体文件、选入字形与运行帧缓冲是不同成本。本站原创MIT概念示意，非实物照片或本站HA运行截图。本站原创 · MIT

参考：[6] ESPHome2026.9.1：字体校验、glyphs与位图生成 [7] ESPHome2026.9.1：运行缺字警告与绘图 [8] ESPHome2026.9.1：SSD1306组件

02 / 屏幕字体

固定128×64和0x3D，再查字号

只支持Adafruit PID326的2020-08后默认I2C/自动复位STEMMA QT修订，2024丝印更新不改变电路。3V3接VIN、共地、GPIO8/J1-12接Data/SDA、GPIO9/J1-15接Clk/SCL，RST留空仅适用此修订。

100kHz短线，模块已有上拉，不无依据再并联。先扫描0x3D并确认型号；匿名128×32或SH1106不能只换一个标题沿用。整屏空白先回电源/总线层，不先把字体换成另一套。

参考：[2] DevKitC-1 v1.1固定提交927ed7e：排针与USB [8] ESPHome2026.9.1：SSD1306组件 [9] PID326官方修订与屏幕能力 [10] PID326 128×64 I2C接线

03 / 屏幕字体

把字体原始字节与许可一起锁住

包内Noto Sans SC Regular来自Noto CJK Sans2.004、commit523d033d6cb47f4a80c58a35753646f5c3608a78。原始OTF8,331,336字节、SHA256=faa6c9df652116dde789d351359f3d7e5d2285a2b2a1f04a2d7244df706d5ea9，未修改。font-lock.json和元数据说明版本，fonts/OFL.txt保留SIL OFL1.1，版权也在原字体metadata中。

YAML/本站说明MIT不覆盖字体许可。ESPHome从该字体生成选入码点位图，字体及衍生位图仍按相应字体许可保留；不靠浮动gfonts URL或网络最新字体去重建另一份结果。

参考：[3] Noto CJK Sans2.004固定发行 [4] 固定Noto Sans SC Regular原始OTF [5] 固定字体SIL Open Font License1.1 [6] ESPHome2026.9.1：字体校验、glyphs与位图生成

04 / 屏幕字体

完整主例：26个字形、16px、1bpp

与H01同版本安装并填私有secrets，先config/compile再按真实串口run。glyphsets为空且glyphs非空，主例列出26个不同码点；同一字符只能列一次，重复的“度”会被该版校验器拒绝。

三个基线行起点为y=0/21/42，默认绘图由固件生成。下面原文可直接与下载核对；画面边界、字形和数字仍需实物观察，不能用源码坐标冒充屏幕截图。

esphome:
  name: esp32-cn-font
  friendly_name: ESP32 Chinese Font
  min_version: 2026.9.1
  on_boot:
    priority: -100
    then:
      - logger.log: "D02-A booted; inspect real device logs"

esp32:
  board: esp32-s3-devkitc-1
  variant: ESP32S3
  flash_size: 8MB
  flash_mode: qio
  flash_frequency: 80MHz
  toolchain: esp-idf
  framework:
    type: esp-idf
    version: 5.5.5

psram:
  mode: octal
  speed: 80MHz

logger:
  baud_rate: 115200
  hardware_uart: UART0
  level: DEBUG

api:
  encryption:
    key: !secret api_key
  reboot_timeout: 0s

ota:
  - platform: esphome
    encryption:
      key: !secret api_key

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  reboot_timeout: 0s
  ap:
    ssid: "esp32-cn-font Recovery"
    password: !secret fallback_password
    ap_timeout: 90s

captive_portal:

i2c:
  id: display_bus
  sda: GPIO8
  scl: GPIO9
  frequency: 100kHz
  scan: true
  timeout: 10ms

font:
  - file: fonts/NotoSansSC-Regular.otf
    id: cn
    size: 16
    bpp: 1
    glyphsets: []
    glyphs:
      - " 0123456789:.%C中文测试温度湿状态正常"

display:
  - platform: ssd1306_i2c
    model: "SSD1306 128x64"
    address: 0x3D
    i2c_id: display_bus
    update_interval: 2s
    lambda: |-
      // Fixed synthetic text for glyph validation, not live sensor values.
      it.print(0, 0, id(cn), "中文测试");
      it.print(0, 21, id(cn), "温度 23.5 C");
      it.print(0, 42, id(cn), "湿度 45.0%");

参考：[1] ESPHome2026.9.1固定版本源码 [6] ESPHome2026.9.1：字体校验、glyphs与位图生成 [7] ESPHome2026.9.1：运行缺字警告与绘图 [8] ESPHome2026.9.1：SSD1306组件

05 / 屏幕字体

用同条件实际构建，比较字集成本

expanded-glyphs.yaml只增加固定额外汉字集，合计281码点，其余板卡、字体、16px/1bpp与显示文本不变；对两份完整配置分别config/compile，保存同环境日志与固件字节，不能用理论位图乘字数充当实测Flash。

原始OTF大小、生成字形数据、完整固件镜像、运行时帧缓冲是四个数字。128×64单色缓冲为1024字节量级；镜像差额还受字体表/链接/对齐影响，不是每汉字恒定成本，更不能称实时RAM峰值。

本轮三个配置都真实编译通过。主例与expanded的OTA差额13,888字节；构建RAM used均107,811字节，只是工具报告的静态量，不是屏幕运行或任务峰值。missing能编译正说明缺字需要额外验收。

实际配置	字形数	OTA镜像字节	构建Flash used	构建RAM used
主例	26	868,576	868,463	107,811
expanded	281	882,464	882,351	107,811
missing	26（故意漏两字）	868,576	868,463	107,811

.venv/bin/esphome config esp32-display-chinese-fonts.yaml
.venv/bin/esphome compile esp32-display-chinese-fonts.yaml
.venv/bin/esphome config expanded-glyphs.yaml
.venv/bin/esphome compile expanded-glyphs.yaml

做到这里，你应该看到: 本轮主例OTA 868,576字节、扩展882,464字节，差13,888字节；镜像SHA与原始日志见证据。

参考：[6] ESPHome2026.9.1：字体校验、glyphs与位图生成 [7] ESPHome2026.9.1：运行缺字警告与绘图 [8] ESPHome2026.9.1：SSD1306组件

06 / 屏幕字体

故意缺两个字，证明能编译还不够

missing-glyphs.yaml保持26字形，却把第一行改为“中文缺字”，有意漏“缺”U+7F3A和“字”U+5B57。字体OTF本来有它们，只是本次没有选入；这份配置可以构建，运行时font查找会警告并绘制缺字占位轮廓。

先保存主例，再烧missing检查真实串口与画面；然后恢复主例，或把真正要显示的新字符加入glyphs并重新编译。新增标签、负号、单位、动态状态时也要补相应码点，不能只想着添加汉字。

漏选码点导致缺字，字形完整但坐标越界导致裁切；两种故障需要不同修复。 — 接线图缺字例能编译，仍必须检查串口与实际画面。本站原创MIT概念示意，非实物照片或本站HA运行截图。本站原创 · MIT

.venv/bin/esphome config missing-glyphs.yaml
.venv/bin/esphome compile missing-glyphs.yaml

参考：[6] ESPHome2026.9.1：字体校验、glyphs与位图生成 [7] ESPHome2026.9.1：运行缺字警告与绘图

07 / 屏幕字体

把乱码、缺字与裁切沿证据分开

主例拍三行全屏，核对中文、数字、小数点、C和百分号；missing例分别记录两码点警告与占位，再恢复正常主例。expanded仍显示同样文本，只比较构建大小，不用它伪造更多画面功能。

仅中文不对先查UTF-8、字体hash、glyphs与所烧配置；所有字都有但边缘截断查字号、坐标和行长；下载缺字体导致config失败时恢复固定OTF和OFL。不要把重装I2C库当所有缺字的修复。

参考：[2] DevKitC-1 v1.1固定提交927ed7e：排针与USB [6] ESPHome2026.9.1：字体校验、glyphs与位图生成 [7] ESPHome2026.9.1：运行缺字警告与绘图 [9] PID326官方修订与屏幕能力 [10] PID326 128×64 I2C接线

08 / 屏幕字体

构建体积是真实结果，屏幕观察仍待实板

本轮实际config、compile与镜像SHA另存；构建正常、扩展与故意缺字三个用例，能把代码链与体积比较复现。本站尚无指定屏运行、缺字警告实录或裁切照片，以上预期都不能勾作实测。

下载同时交付完整字体及许可、全部YAML、依赖锁、README与空记录模板。物理结果仍由读者按同一模块/版本执行；字体码点范围或屏幕更换后重新验证。

参考：[3] Noto CJK Sans2.004固定发行 [4] 固定Noto Sans SC Regular原始OTF [5] 固定字体SIL Open Font License1.1 [6] ESPHome2026.9.1：字体校验、glyphs与位图生成 [7] ESPHome2026.9.1：运行缺字警告与绘图 [8] ESPHome2026.9.1：SSD1306组件

BACK TO THE SOURCE

资料来源与版本说明

本文依据下列官方文档与上游资料独立整理，适用范围与版本以本文所列组合为准。资料核对日期：2026-10-18。资料核对、程序构建与实板测试分别记录，不互相替代。