用 TFT_eSPI 驱动库点亮你的第一块 SPI 屏幕：从引脚配置到第一帧画面-开发者社区

用 TFT_eSPI 驱动库点亮你的第一块 SPI 屏幕：从引脚配置到第一帧画面

【免费下载链接】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 是一个兼容 Arduino 与 PlatformIO 的 TFT 驱动库，针对 ESP32、ESP8266、树莓派 Pico（RP2040）和 STM32 做了优化。读完这篇，你能完成接线、选对配置文件，让屏幕显示出第一行文字。

🎯 它能替你解决什么

做物联网面板时：不用它，每换一种驱动芯片都要自己写 SPI 事务和初始化命令序列，代码又长又容易错；用它，只换一个 setup 文件，绘制代码原样跑通。

做工业 HMI 或仪表盘时：自带的抗锯齿 Smooth Fonts 和平滑图形，让刻度、数值显示得干净，不用手工调点阵字模。

做 DIY 掌机、时钟时：Sprite 缓冲把一整帧画在内存里再一次性刷到屏上，动画不撕裂。

这三点清楚了，下面把环境搭起来。

🛠️ 环境准备与安装：TFT_eSPI 引脚配置速查

获取库：在 Arduino IDE 的 Library Manager 里直接搜 TFT_eSPI 安装；或执行git clone https://gitcode.com/GitHub_Trending/tf/TFT_eSPI，把仓库放进 Arduino 主目录下的 libraries 文件夹（PlatformIO 用户放项目的 lib 目录）。
选配置文件：在 User_Setups/ 目录里按"板子 + 驱动芯片"找。举例：ESP32 + TTGO T-Display 用Setup25_TTGO_T_Display.h，Pico + ILI9341 用Setup60_RP2040_ILI9341.h，其余组合在该目录自行对照查找。
选中它：编辑库根目录的User_Setup_Select.h，把对应的#include行取消注释，并保持只有这一行生效。
核对引脚与驱动：在 setup 文件里确认TFT_CS、TFT_DC、TFT_MOSI、TFT_SCLK与你的实际接线一致，驱动芯片宏（如ILI9341_DRIVER）与屏幕匹配。
接线：SPI 屏的关键线是 VCC、GND、CS、DC、RESET、MOSI、SCLK；下图给出 ESP32 UNO 板的 SPI 引脚参考与底面改线位置。

ESP32 开发板 TFT SPI 引脚接线参考图

ESP32 UNO 板 8 位并行 TFT 接线改线图

▶️ 跑通第一帧：最小初始化代码

下面的示例只做三步：初始化、清屏、打印一行文字。硬件差异全部交给 setup 文件，所以 sketch 本身很薄。

#include <TFT_eSPI.h> TFT_eSPI tft = TFT_eSPI(); void setup() { tft.init(); tft.setRotation(1); tft.fillScreen(TFT_BLACK); tft.setTextColor(TFT_WHITE); tft.setTextSize(2); tft.setCursor(0, 0); tft.println("Hello, TFT_eSPI!"); } void loop() {}

烧录成功后，你应该看到黑底上的白色文字。如果整屏偏蓝偏绿，先查 setup 文件里的驱动芯片是否和屏幕一致；如果颜色"反了"（发粉、发青），把 setup 文件中的TFT_RGB_ORDER取消注释试一次。完全无显示时，先量供电与 RESET 线，再运行 examples/Test and diagnostics/ 里的诊断示例。更多按分辨率分好类的图形测试在 examples/ 目录，按你的屏幕尺寸挑。

⚡ 进阶能力速览

平滑字体—— 抗锯齿平滑文字，支持 Unicode 字符，字体文件可放文件系统或直接烧进 Flash：examples/Smooth Fonts/
Sprite 精灵—— 无闪烁动画的离屏缓冲，支持 1/8/16 位色深：examples/Sprite/
触摸输入—— 内置 XPT2046 触摸控制器支持：Extensions/Touch.h
抗锯齿图形—— 平滑圆弧、圆、圆角矩形描边：examples/Smooth Graphics/
图片显示—— BMP、JPG、PNG 的加载与绘制示例：examples/PNG Images/
GUI 控件—— 按钮、滑块、仪表、曲线演示：examples/GUI Widgets/

⚠️ 高频踩坑与自查清单

初始化后屏幕全黑→ 先确认User_Setup_Select.h真的指向你改过的那份 setup（默认指向根目录的User_Setup.h），再检查 DC 与 RESET 线：User_Setup_Select.h
颜色反相或红蓝互换→ 在 setup 文件里依次取消注释TFT_INVERSION_ON、TFT_RGB_ORDER各试一次：User_Setup.h
画面偏移、边缘留黑边→ ST7789、ST7735、GC9A01 需要手工定义TFT_WIDTH与TFT_HEIGHT，从模板文件开始改：User_Setups/SetupX_Template.h
屏幕初始化后 SD 卡失联→ SPI 总线共用时必须在 setup 里显式定义 TFT_MISO、TFT_MOSI、TFT_SCLK，README 中有专门说明：README.md
PlatformIO 用户不想动库内文件→ 在 platformio.ini 中用TFT_ESPI_USER_SETUP_PATH指定外部 setup 文件即可：docs/PlatformIO/