TFT_eSPI 点亮TFT屏幕只需4步，附配置文件与避坑自查清单

【免费下载链接】TFT_eSPIArduino and PlatformIO IDE compatible TFT library optimised for the Raspberry Pi Pico (RP2040), STM32, ESP8266 and ESP32 that supports different driver chips项目地址: https://gitcode.com/GitHub_Trending/tf/TFT_eSPI

TFT_eSPI 是一款面向 ESP32、ESP8266、树莓派 Pico（RP2040）和 STM32 的 TFT 显示屏驱动库，走 SPI 或并行总线，把文字、图形、图片和触摸交互做成开箱即用的函数。它的核心设计是：驱动芯片、引脚、SPI 频率等所有硬件配置都集中在一个配置文件里，配好一次，仓库自带示例几乎不用改动就能直接烧录。如果你手上有一块 3.5 英寸或 2.8 英寸的 TFT 屏想驱动起来，这篇就按顺序带你走一遍。

📦 环境核对：先确认你的硬件在支持名单里

动手前，把下面这张表过一遍。任何一项对不上，后面步骤都会卡住。

各处理器的接口能力不同，对照 README 中的官方矩阵：

官方建议新手从 SPI 接口的 ILI9341 或 ST7796 屏起步，这两种屏的示例和资料最全。

🔌 点亮首屏：四步走完看到画面

第 1 步：把库放进工程

两种方式任选：

• 在 Arduino IDE 的 Library Manager 里搜索 TFT_eSPI 直接安装（当前版本 2.5.44）；
• 或把仓库 clone 到本地再指向它：

git clone https://gitcode.com/GitHub_Trending/tf/TFT_eSPI

第 2 步：选对并修改配置文件

TFT_eSPI 的配置机制是"一个文件说了算"。编译器真正读哪个配置，由 User_Setup_Select.h 决定：其中有一行生效的#include <User_Setup.h>（指向库根目录的默认配置），其余是一长串被注释的现成配置。

操作分两种情况：

1. 有现成匹配项：User_Setups/ 里有几十个按"开发板 + 驱动芯片"命名的配置，例如 ESP32 配 TTGO T-Display 选Setup25_TTGO_T_Display.h，RP2040 配 ILI9341 选Setup60_RP2040_ILI9341.h。把对应那行的//去掉，同时注释掉默认行。
2. 没有匹配项：复制 User_Setups/SetupX_Template.h 改名，按注释填写。

无论哪种，进配置后重点核对五处：驱动宏（如#define ST7789_DRIVER，只能保留一个）、引脚（TFT_MOSI、TFT_SCLK、TFT_CS、TFT_DC、TFT_RST，背光可选TFT_BL）、分辨率（ST7789、GC9A01 等需定义TFT_WIDTH/TFT_HEIGHT）、SPI_FREQUENCY、字体开关（LOAD_FONT2、LOAD_GFXFF、SMOOTH_FONT）。

用 PlatformIO 的话，在platformio.ini里定义TFT_ESPI_USER_SETUP_PATH指向外部配置即可，方法见 docs/PlatformIO/。

提醒一句：升级库会覆盖库目录里的配置文件。建议把自己的配置放在库文件夹外，在User_Setup_Select.h里用#include <../你的路径/你的配置.h>指向它，并另存一份备份。

第 3 步：接线

SPI 屏最少 7 根线：VCC、GND、SCK、MOSI、MISO、CS、DC（丝印上也常写成 RS 或 A0），再加 RESET 和可选背光 BL。DC 是数据/命令切换线，接错它屏幕只会闪一下花。

树莓派 V3.0 3.5 英寸屏的接法，直接照图来：

如果你用的是 UNO 外形 ESP32 板 + 8 位并行屏（mcufriend 风格），板子需要飞线修改，修改位置和引脚对照如下：

ESP32 UNO板并行接口TFT接线修改照片

ESP32 UNO板引脚分配与TFT_eSPI引脚定义对照

第 4 步：跑最小示例

新建一个 sketch，只写这几行：

#include <TFT_eSPI.h> TFT_eSPI tft = TFT_eSPI(); void setup() { tft.init(); tft.fillScreen(TFT_BLACK); tft.setTextColor(TFT_WHITE); tft.setCursor(0, 0); tft.println("First screen, on."); } void loop() {}

编译上传，屏幕上出现 "First screen, on." 就说明驱动、引脚、接线三件事全对了。之后可以从 examples/Test and diagnostics/ 里挑Colour_Test、TFT_ReadWrite_Test、Read_User_Setup依次验证色彩、读写回环和当前生效的配置。

🖼️ 场景化进阶：按你的需求找目录

显示图片

• BMP：examples/Generic/TFT_SPIFFS_BMP/ 演示从 Flash 文件系统读图；Tools/bmp2array4bit/ 提供脚本把 bmp 转成 C 数组。
• JPG：examples/160 x 128/TFT_flash_jpg/ 把 jpg 预编译进 Flash 再解码。
• PNG：examples/PNG Images/ 支持带透明通道的 PNG，LittleFS、Flash 数组、DMA 三种读法都有示例，注意需约 40KB RAM。

绘制图形与平滑字体

• 抗锯齿圆弧、圆、圆角矩形（无毛刺的仪表盘效果）：examples/Smooth Graphics/。
• 平滑字体：字体文件为 vlw 格式，支持存 SPIFFS、LittleFS、SD 卡或直接编译进 Flash 数组，examples/Smooth Fonts/ 下按存储方式分了四个子目录。要生成 vlw，用 Processing 跑 Tools/Create_Smooth_Font/，任意 ttf 字体都能转，支持全 16 位 Unicode 字符。

精灵做动画

Sprite 是一块 RAM 里的"隐形画布"（代码在 Extensions/Sprite.h）：先整块画好，再一次性贴到屏幕上，因此指针、表盘这类高频刷新不闪烁。色深可选 16/8/1 位以省 RAM，examples/Sprite/ 里有旋转精灵、滚动、透明贴图、指针表盘（Animated_dial）等完整案例。

触摸交互

XPT2046 触摸芯片的支持已内置：在配置里定义TOUCH_CS引脚即可（仅 SPI 屏支持）。先跑 examples/Test and diagnostics/Test_Touch_Controller/ 确认通信，再做校准 examples/Generic/Touch_calibrate/；想要按钮、滑块、仪表这类控件，看 examples/GUI Widgets/，底层代码在 Extensions/Touch.h 与 Extensions/Button.h。

🐛 屏不听话时：按这张表自查

✅ 下一步去哪

首屏点亮后，配置、驱动和示例这三类资料就够你走完大多数项目：User_Setups/ 找板级配置，examples/ 按分辨率和功能分类找示例，docs/ 里是 ESP-IDF、PlatformIO 和各板接线的补充说明。遇到具体问题，先跑一遍 diagnostics 示例，把实际生效的配置打印出来，比反复猜接线快得多。

【免费下载链接】TFT_eSPIArduino and PlatformIO IDE compatible TFT library optimised for the Raspberry Pi Pico (RP2040), STM32, ESP8266 and ESP32 that supports different driver chips项目地址: https://gitcode.com/GitHub_Trending/tf/TFT_eSPI