简介：TFT_eSPI-master.zip 是适用于 Arduino、ESP32 等微控制器平台的 TFT 液晶屏图形库，由 Bodmer 维护，旨在解决原生 TFT 驱动库渲染慢、屏幕兼容性差的问题。库内同时提供 TFT_eSPI 主类、Font 字体类与 GFX 图形函数封装，可驱动 SPI、I2S、Parallel 多类接口的彩色屏，并覆盖绘图、文字、位图、动画及触摸屏支持，适合需要为物联网设备、仪表盘或游戏界面快速搭建显示层的开发者。

包内共 500 个文件，压缩后约 5MB，以 h 头文件和 ino 示例程序为主，辅以 c/cpp 核心实现、vlw 字体、bmp/jpg/png 图片素材及 md 说明文档。通过示例工程和源码对照，可以快速理解引脚配置、颜色深度设置、println、fillRect、pushImage 等常用 API 的实际调用方式，便于移植到不同板卡。包内目录结构清晰，源码、示例、字体与图片素材各自归类，便于按需提取。

已有 1116 人学习、下载，适合嵌入式入门者评估驱动库结构，也适合中高级开发者作为自定义屏显方案的参考基准。

1. TFT_eSPI 压缩包值不值得拆：先看它解决了什么问题

有开发者在智能家居面板项目里用一块 320×240 的 RGB565 TFT 屏，跑旧图形库做仪表盘动画，全屏刷新肉眼可见的拖影和撕裂。他用的是 ESP32 主控，SPI 总线上挂着一个触摸屏，CPU 主频 240MHz，理论算力不差，但屏幕却成了整个系统的木桶短板。换用 TFT_eSPI 这个驱动方案后，同样一块屏、同一根线缆，刷屏速度提升了十倍以上，绘制 2D 图形从「一格一格地扫」变成「整帧弹出来」。TFT_eSPI 不是魔法，它只是把 SPI 屏幕驱动的底层细节——协议时序、帧缓冲、DMA 搬运、字体渲染——全部收拢成了一套线程安全的接口。这份 zip 资源适合正在用 ESP32、ESP8266 或 STM32 做屏幕项目的开发者，尤其是被逐点绘制和缓慢刷新折磨过的人。

2. 目录结构与 User_Setup.h：把驱动芯片和引脚一次配到位

拿到TFT_eSPI-master.zip，第一件事不是解压就编译，而是先弄清楚这套库的配置机制。它跟普通 Arduino 库最大的区别在于：很多配置不是写在setup()里，而是写在一个会被编译期读取的头文件中。配错了，轻则花屏，重则白屏，且报错信息往往跟实际原因对不上。

2.1 解压后目录结构：套娃文件夹和三个必须认识的配置头文件

解压 zip 后你会看到最外层是TFT_eSPI-master文件夹，里面通常还套着一层同名文件夹。直接把内层这个文件夹拷到开发环境的libraries目录，并改名为TFT_eSPI，否则开发环境按库名索引时会识别不到。这种「zip 自带根目录再套一层」的结构在开源资源里非常常见，算是一个经典安装坑。

进入库根目录后，有两个头文件你迟早要打交道：

• User_Setup.h：主配置文件，定义了使用的屏幕驱动芯片型号、SPI 引脚映射、分辨率、颜色格式等核心参数。
• User_Setup_Select.h：配置选择器，它像路由器一样决定到底加载哪一套用户配置。默认它指向User_Setup.h，如果你有多块屏或多块板子的配置，可以把多份配置存成不同文件，在这里条件编译切换。

库源码里还有TFT_eSPI.cpp和TFT_eSPI.h，这两个文件是驱动核心实现，日常不需要改，但排查问题时可以打开它们查寄存器操作。另外tools目录里是字体转换工具，后面讲自定义字库时会用到。

2.2 User_Setup.h 核心参数：驱动芯片、引脚、SPI 频率逐行拆

以一块常见的 ST7789 驱动、分辨率 240×320、四线 SPI 接口的屏幕为例，User_Setup.h里需要确认以下配置段：

// 驱动芯片定义，选错型号会导致初始化命令完全不对 #define ST7789_DRIVER // RGB 顺序，某些屏颜色偏蓝或偏红就是这里反了 #define TFT_RGB_ORDER TFT_BGR // 分辨率，注意部分屏幕物理方向是 240x320，横屏后要交换 #define TFT_WIDTH 240 #define TFT_HEIGHT 320 // 引脚定义，按实际接线修改，这里是一组常用映射 #define TFT_CS 15 #define TFT_DC 2 #define TFT_RST 4 #define TFT_MISO 12 #define TFT_MOSI 13 #define TFT_SCLK 14 // SPI 通信频率，单位 Hz。32 位 ESP 系列可到 80MHz，但实际看杜邦线 #define SPI_FREQUENCY 40000000

逐个参数说明一下：

• 驱动芯片：ST7789、ILI9341、ST7735 是市面上最主流的几款控制芯片，它们虽然都走 SPI，但初始化命令集不同。选错型号最常见的结果是白屏或显示异常色块。
• TFT_RGB_ORDER：如果你刷纯红色却发现显示纯蓝，基本都是这个宏反了，把TFT_BGR改成TFT_RGB即可。
• 引脚映射：CS是片选，DC是数据/命令选择线，RST是硬件复位。MISO 在只写屏幕时可以不用，但触摸屏和 SD 卡读操作必须接。
• SPI_FREQUENCY：我这里写的是 40MHz，跑杜邦线很稳。后面会专门讲频率过高导致的信号完整性问题。

提示：开发环境首次编译完成后，如果你用的平台带缓存机制，改User_Setup.h后必须强制重新编译，否则旧的配置可能被缓存复用。

2.3 多屏与多板卡切换：用配置文件替身省掉反复改代码

真实项目里最常见的场景是：同一套代码，今天焊了一块带触摸的屏，明天换了一块不带的。如果每次都在User_Setup.h里注释来注释去，很容易出现「上周还能亮，这周白屏」的玄学问题。

常见做法是在User_Setup_Select.h里按板卡型号做条件编译，例如：

#define SETUP_A // 选择第一套配置，实际写在 User_Setup.h

更干净的方案是把每套配置拆成独立头文件。比如User_Setup_ST7789.h和User_Setup_ILI9341.h，在User_Setup_Select.h里改成：

#define ST7789_CONFIG

然后在这个选择文件里用#ifdef包含对应配置头文件。每次换屏幕只动一个宏，代码逻辑里完全不用改引脚和屏幕参数。这对硬件版本迭代比较频繁的团队尤其友好。

3. 帧缓冲与 DMA 加速：把刷屏从 15 帧提到 60 帧的底层逻辑

很多初学者第一次接触 TFT_eSPI 时只把它当普通库用，画个点、画个圆，跟旧图形库没区别，速度也没体现出优势。直到把绘制方式从「逐点」改成「整帧缓冲」后，才真正感受到差距。这一章讲清楚为什么会快，以及快在哪里。

3.1 逐点绘制的开销拆解：为什么坐标越多越慢

屏幕是 SPI 从设备，主控向它写一个像素点，需要先发一长串命令与数据。以设置像素坐标为例，底层要走三次 SPI 事务：设置列地址、设置行地址、写入颜色数据。每笔事务都有协议开销和 CS 片选电平翻转的时序代价。

假设你画一条 240 像素的横线，逐点调用旧图形库的drawPixel：

for (int x = 0; x < 240; x++) { tft.drawPixel(x, 100, TFT_RED); }

这段代码实际发生的是一百多次独立的 SPI 写事务，每次都要重新拉低 CS、发送坐标和命令、最后把颜色数据写进去。SPI 时钟 40MHz 时，单次事务的纯协议开销就有几十微秒，加上坐标计算和函数调用栈，整条线跑下来比批处理慢一个数量级。

TFT_eSPI 的思路是提供区域填充接口，用一次事务把整块矩形区域的颜色数据推过去，把「鼠标点菜」变成「整盘端上」。

3.2 帧缓冲与 pushImage：一次推一帧而不是一千个点

帧缓冲（framebuffer）的核心是准备一块与屏幕分辨率对应的内存区域，先在内存里完成所有绘制逻辑，最后统一推送到屏幕。对一个 240×320 的 RGB565 屏幕，像素数据量是 240×320×2 字节，约 153.6KB。ESP32 内部 RAM 足够放下，但如果你用的是普通 ESP32 不带 PSRAM，分配这块缓冲区会吃紧，需要精打细算。

TFT_eSPI 实现帧缓冲最直接的方式是用 Sprite 类：

#include <TFT_eSPI.h> TFT_eSPI tft = TFT_eSPI(); TFT_eSprite sprite = TFT_eSprite(&tft); void setup() { tft.begin(); tft.setRotation(1); // 横屏 // 创建与屏幕同尺寸的完整帧缓冲 sprite.setColorDepth(16); // RGB565 sprite.createSprite(320, 240); // 宽 x 高 } void loop() { // 在内存中的 sprite 里绘制 sprite.fillSprite(TFT_BLACK); sprite.fillCircle(160, 120, 60, TFT_BLUE); sprite.setTextColor(TFT_WHITE, TFT_BLACK); sprite.drawString("FPS test", 100, 110, 2); // 一次性推送整个缓冲区到屏幕 sprite.pushSprite(0, 0); delay(16); }

这里的核心逻辑分两步：先在内存里画，画完后用pushSprite把整块数据一次推给屏幕驱动。这个过程因为省去了重复的坐标设置事务，画面绘制时间可以从几百毫秒级降到几十毫秒级。

注意：createSprite的宽高参数是「先宽后高」，别与屏幕初始化时的TFT_WIDTH、TFT_HEIGHT混淆。拧过很多次才记得，横屏后这两个值是要交换的。

3.3 DMA 传输：让 SPI 自己搬数据，CPU 回去睡觉

有了帧缓冲还不够，如果把整帧数据用 CPU 逐字节搬运到 SPI 外设寄存器，CPU 依然被大量占用。ESP32 的 SPI 外设支持 DMA（Direct Memory Access 直接内存访问），可以让数据从内存到外设这条链路完全由硬件完成，CPU 只在发起传输时参与，传输期间可以去做别的任务。

TFT_eSPI 在User_Setup.h里默认开启 DMA 宏：

#define SPI_FREQUENCY 40000000 #define USE_DMA

开启USE_DMA后，pushImage和pushSprite系列接口内部会走 DMA 路径。实际使用中你不需要手动操作 DMA 描述符，只要确保传入的图像数据源是一块连续内存。例如：

uint16_t* buffer = (uint16_t*)heap_caps_malloc( 320 * 240 * 2, MALLOC_CAP_DMA); if (buffer == NULL) { // 分配失败时降级到普通内存，DMA 会退化为普通 SPI } // 填充图像数据后直接推送 tft.pushImage(0, 0, 320, 240, buffer);

关键点在分配内存的MALLOC_CAP_DMA标志。普通malloc分配的内存可能位于 cache 不友好的区域，DMA 读取会出现数据不一致或性能下降。从实践经验看，第一次跑 DMA 图案错乱，十有八九是内存分配没加这个标志。

DMA 开启后，全屏pushSprite的耗时可以从数十毫秒降到十毫秒以内，刷新率轻松到达 60fps 以上，CPU 还可以抽空跑动画逻辑、触摸读取和网络任务。这也是 TFT_eSPI 在动画场景下明显优于逐点绘制方案的关键。

4. 字体与图像渲染：从内置 ASCII 到自定义中文字库

屏幕项目一旦涉及中文显示，TFT_eSPI 默认只带 ASCII 字库的问题立刻暴露。单纯的英文字符和数字是够用的，但中文、特殊图标都需要走自定义字体路线。这一章把整个链路理清楚。

4.1 内置字体与绘制 API 坐标规则

TFT_eSPI 内置了多套数字编号的字体，从1到8不等，分别对应不同字号和比例。字体 ID 越小，绘制越快，占用 Flash 越少。调用方式：

tft.setTextColor(TFT_WHITE, TFT_BLACK); tft.setTextSize(2); // 整数倍缩放 tft.setCursor(10, 20); tft.print("Hello TFT_eSPI");

规格上要注意三点：setTextSize只支持整数倍缩放，想要精确字号必须用自定义字体；setTextColor(前景, 背景)如果背景色设为与屏幕底色不同，背景矩形会自动填充，这会影响绘制速度；坐标原点是屏幕左上角，横屏后原点在物理长边的左上，不是物理屏的左上。

4.2 自定义字体：把 TTF 转成 C 头文件的工具链

针对中文显示，TFT_eSPI 提供了一整套字体转换链路。推荐在电脑上装 Processing 环境，然后运行库tools目录下名为fontconvert的 Processing 脚本，把系统 TTF 字体转成一个.h头文件。转换完成后，在代码中加载该字库并绘制：

#include "my_font.h" // 由 fontconvert 生成的字体头文件 void setup() { tft.begin(); tft.loadFont(my_font); // 从 Flash 加载 } void loop() { tft.setTextColor(TFT_WHITE); tft.drawString("中文字体测试", 20, 50); }

参数上，fontconvert 有三个关键参数：字体文件路径、字符集范围、输出文件名。中文字符集务必按 GB2312 或 UTF-8 常用字范围裁剪，如果把全汉字集都塞进一个头文件，生成的文件可能超过 1MB，Flash 小的芯片直接编译失败。

实际项目中更稳妥的做法是只转你实际用到的几十个汉字。比如做「温度、湿度、风速」面板，就把这几个词涉及的字符挑出来做成一个微型字库，加载速度和内存占用都优于全量字库。不过这种方式扩充新字需要重跑工具链，所以我一般会保留一份常用的 200 字基础字库，再为每个项目追加专属字符。

4.3 图像解码与 SPRITE 位块传输

除了字体，图像显示是项目里另一个高频需求。TFT_eSPI 本身不做 JPEG/PNG 解码，但它的pushImage接口可以直接接收解码后的 RGB565 像素数组。常见的做法是引入 JPEG 解码库，从 SD 卡读取图片，解码后一行一行推给屏幕：

uint16_t* imgBuf = (uint16_t*)malloc(320 * 240 * 2); // 解码库逐块解码 JPEG，输出 RGB565 数据到 imgBuf // 解码完调用 pushImage tft.pushImage(0, 0, 320, 240, imgBuf);

需要注意解码库输出的像素格式：很多时候解码库输出 24 位 RGB888，而 TFT_eSPI 需要 16 位 RGB565，中间需要做一次格式转换。转换是纯 CPU 计算，如果做全屏图，单帧转换耗时比 SPI 传输还高，建议在 PC 端预处理图片时就直接保存为 RGB565 的 raw 数据。

SPRITE 是 TFT_eSPI 另一个常用模块，适合做小尺寸精灵图。前面讲到的整屏帧缓冲其实就是超大 Sprite；小 Sprite 常用于 UI 图标、弹窗、动画物体。用法与屏幕子区域类似：

TFT_eSprite icon = TFT_eSprite(&tft); icon.createSprite(32, 32); icon.fillSprite(TFT_TRANSPARENT); // 透明色支持 icon.fillCircle(16, 16, 12, TFT_RED); icon.pushSprite(50, 80); // 把图标贴到屏幕指定位置

透明的 Sprite 可以组合多个图层，实现无撕裂的局部刷新，这在仪表盘和 HUD 界面中极其实用。

5. TFT_eSPI 避坑记录：五个翻车场景与对应修复

用 TFT_eSPI 做项目的过程中，遇到过的坑基本都能归类到配置、硬件接线、内存和编译环境四个方向。这一章整理的五个问题是复现率最高的，每一条都按「现象 → 原因 → 解决」梳理，方便你直接对照排查。

5.1 现象：屏幕出现随机条纹、雪花点，刷新时局部错乱

原因：SPI 时钟频率超出线缆和接线方式能承受的极限。调试时为了追求极致帧率，把SPI_FREQUENCY拉到了 80MHz，但用的是十几厘米杜邦线飞线连接，信号反射和串扰严重，数据位在传输过程中被损坏。

解决：先把频率降到 40MHz 甚至 26.7MHz 测试。

#define SPI_FREQUENCY 40000000

如果必须跑高频率，要从物理层面优化：换成双排排针短接或 FPC 软排线，MOSI 和 SCLK 之间避免平行长距离走线。记住一点：SPI 频率能跑多快，不取决于芯片手册标称，而取决于你手里那根线的实际质量。

5.2 现象：屏幕全白、背光亮，代码初始化没有任何反应

原因：RST引脚配置错误或悬空。部分屏幕模块的复位引脚内部没有上拉，主控不主动拉低再释放，驱动芯片就停在未知状态。初期测试时偷懒没接RST，以为靠上电时序能自动复位，结果白屏了半天。

解决：确认User_Setup.h中TFT_RST已定义且实际接线无误。如果强行不想占用一个 GPIO，可以把TFT_RST定义成-1，让库在初始化时用软件复位方式驱动芯片。这个技巧可以避免为复位功能单独占用一个引脚，但软件复位的兼容性因芯片而异，ST7789 表现尚可，部分老型号 ILI9341 则不稳定。

5.3 现象：编译环境提示找不到 TFT_eSPI 库，或者包含的库版本不对

原因：zip 解压后目录嵌套产生的路径错误。开发环境识别库的标准是：libraries目录下直接看到一个名为TFT_eSPI的文件夹，其中包含TFT_eSPI.h。而 zip 解压出的是TFT_eSPI-master/TFT_eSPI，外层文件夹名不符，内层又没有直接放在libraries下。

解决：只保留内层目录，改名TFT_eSPI后放回libraries。顺便检查User_Setup_Select.h里是否有多个SETUP宏同时被定义，如果有，只能保留一个，否则配置头文件包含逻辑会冲突。

5.4 现象：触摸屏坐标错乱，点击目标按键却触发旁边区域

原因：触摸校准数据没有持久化，或者屏幕旋转角度与触摸坐标轴对应关系错误。很多示例代码直接写死一个校准偏移量，换一块屏或换一次旋转角度，偏移量就失效了。

解决：用内置校准函数跑一遍四点校验，然后把校准参数存入 NVS 或 SD 卡配置文件中。利用系统自带参数存储 API 保存校准值：

#include <Preferences.h> Preferences prefs; void saveCal(uint16_t* calData) { prefs.begin("tft", false); prefs.putBytes("cal", calData, 8 * sizeof(uint16_t)); prefs.end(); } void loadCal(uint16_t* calData) { prefs.begin("tft", true); prefs.getBytes("cal", calData, 8 * sizeof(uint16_t)); prefs.end(); }

首次开机跑校准，之后启动时直接读取。校准值务必与setRotation的旋转值绑定存储，旋转一变，校准数据就要重新生成。

5.5 现象：启用整屏 Sprite 后程序反复重启或绘制异常

原因：内存分配失败。前面算过，240×320 的 RGB565 完整帧缓冲需要约 150KB 内存。ESP32 在没有 PSRAM 的情况下，剩余可用堆可能不足，createSprite返回空指针，后续绘制操作全部作用于无效地址，触发看门狗重启或异常复位。

解决：分配前检查返回值，并准备降级方案。

TFT_eSprite sprite = TFT_eSprite(&tft); sprite.setColorDepth(16); bool ok = sprite.createSprite(240, 320); if (!ok) { // 降级为行缓冲，每次刷一行 sprite.createSprite(240, 16); }

如果项目确实需要整屏缓冲，换个思路：直接买带 PSRAM 的 ESP32 模组，成本略高但省心太多。另一个常用技巧是减小颜色深度，setColorDepth(8)可以把缓冲占用砍半，但颜色精度下降，做渐变图形时会出现明显色阶，需权衡。

6. 用帧率实测校准你的优化方向：附一个可复用测试脚本

每拿到一块新屏，我习惯先跑一段标准帧率测试，把当前配置下的实际刷新性能量化出来，再决定优化方向。这里提供一个固定流程的测试写法：

uint32_t frameCount = 0; uint32_t startMillis = millis(); void loop() { sprite.fillSprite(TFT_NAVY); sprite.drawString("FPS", 120, 100, 4); sprite.pushSprite(0, 0); frameCount++; if (frameCount >= 60) { uint32_t elapsed = millis() - startMillis; float fps = frameCount * 1000.0 / elapsed; Serial.printf("FPS: %.1f\n", fps); frameCount = 0; startMillis = millis(); } }

这个测试每画满 60 帧才计算一次平均帧率，避免单帧抖动影响判断。测试不同配置时，只需要改三处：屏幕旋转方向、是否开启 DMA、缓冲层数。

在几个典型配置组合下，用 240×320 ST7789 实测，帧率区间大致如下表：

表格里最值得关注的是「局部 Sprite 缓冲」这种折中方案。它内存占用只有整屏缓冲的十分之一，帧率却能逼近整屏加 DMA 的一半。很多项目其实不需要全屏 60fps，一个 64×64 的局部 Sprite 做仪表盘指针，足够流畅且内存成本低，翻车的概率也小得多。

渲染模式的选型有一条判断标准：如果你在动画中同时需要显示大面积静态背景，把背景做成图片直接推屏，把动态元素做成小 Sprite 叠加，效果优于整屏重绘。这是从一次次帧率实测对比中得出的经验。

最后分享一个自己踩过的坑：某次项目交付前，客户反馈屏幕偶尔闪一下，排查了两天无果，最后发现是测试代码里把pushSprite和delay()放在了中断回调里，导致 SPI 事务被中断抢占。从那以后，我每次做屏幕驱动都会强制走一遍「固定帧率测试 → 调整渲染模式 → 观察最坏情况」的流程，确认所有 SPI 操作都在主循环或受保护的任务中执行，再考虑性能优化。

希望这份拆解能帮你把 TFT_eSPI 的资源吃透，少走弯路。

本文还有配套的精品资源，点击获取