企业官网建设流程全解析

从点亮屏幕到画出界面：TFT_eSPI 玩转 ESP32 + TFT 屏的完整实操指南

【免费下载链接】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

如果你打算给设备加一块彩屏——仪表盘、气象站、测量面板都算——这篇文章就按一个真实小项目带你走完全程：给 ESP32 配一块 TFT 屏，用 TFT_eSPI 库完成安装、接线、配置和第一张图，最后把最常见的翻车点逐一讲清楚。TFT_eSPI 是一个面向 RP2040、STM32、ESP8266、ESP32 优化的 Arduino/PlatformIO 兼容图形库，自带 ILI9341、ST7789、GC9A01 等 20 款驱动芯片的初始化代码，画线画圆画字一应俱全。

给项目加一块 TFT 屏，要解决哪些问题

先把场景说清楚：手头有个 ESP32 项目，数据在串口里躺着，现在想加一块 240×240 的彩屏实时显示。这个需求拆开看，其实就四件事，TFT_eSPI 恰好每件都有现成方案：

另外两个容易忽略的加分项：ESP32、RP2040、STM32 的 SPI 屏可以开 DMA 渲染；XPT2046 触摸芯片的支持直接内置，不用另找库。

TFT_eSPI 安装步骤：Arduino IDE 与 PlatformIO 两条路

安装本身没门槛：

• Arduino IDE：库管理器里搜TFT_eSPI，点安装。
• PlatformIO：在platformio.ini的依赖里加一行lib_deps = TFT_eSPI。

装完先别急着写代码，这个库有个和别的库不太一样的地方：所有硬件参数都不允许写在 sketch 里，必须放在库的配置文件中。这其实是优点——配置一次，所有示例程序不用改一行就能直接跑。配置体系分三层，记住名字就够：

1. User_Setup.h：主配置文件。在这里定义驱动芯片（#define ILI9341_DRIVER之类）、引脚映射、SPI 频率、要载入哪些字体。
2. User_Setup_Select.h：选择器。里面是一长串被注释掉的 include，把哪一行取消注释，编译器就用哪套配置，适合手里有好几块屏的人。
3. User_Setups/：预设目录。比如Setup1_ILI9341.h（ESP8266 + ILI9341）、Setup135_ST7789.h、Setup200_GC9A01.h，还有 LilyGo、TTGO 等成品开发板的现成配置，能直接用就别自己写。

PlatformIO 用户还有个小技巧：在platformio.ini里定义TFT_ESPI_USER_SETUP_PATH指向自己项目里的配置文件，每个工程可以用各自的硬件参数，互不干扰，详见 docs/ 下的 PlatformIO 说明。

⚠️ 提醒一句：升级库时User_Setup.h和User_Setup_Select.h的改动会被覆盖，自己改过的配置记得备份一份。

接线：ESP32 与树莓派接 TFT 屏怎么连

SPI 接口的屏，信号线基本是一套：电源、GND、SCK（时钟）、MOSI（数据）、CS（片选）、DC（也叫 RS 或 A0，区分数据/命令）、RST（复位），有的屏多一根背光控制线 BL、一根 MISO（触摸或读寄存器用）。

拿最常见的 3.5 英寸树莓派屏（HUGA 480×320，ILI9486/ST7796 驱动）举例，图里把每根线标得清清楚楚，MISO 和 T_CS 只在带触摸时才需要接：

树莓派屏的更多接线细节可以翻 docs/RPi_TFT_connections/。

如果你的 ESP32 是 UNO 板型的，想跑 8 位并口提速，可以参考官方给的底板改装思路——把并口信号引到底部一排针脚上：


改装前先把这块板的引脚分布认全，SPI 四根线、并口数据线和电源都在板上标了名字：


第一次点亮屏幕：tft.init() 最短启动代码

线和配置都对上之后，用下面这段最短的代码验证硬件。编译上传，看到黑底白字就算成功：

#include <TFT_eSPI.h> TFT_eSPI tft = TFT_eSPI(); void setup() { tft.init(); // 初始化驱动芯片和引脚 tft.setRotation(1); // 画面旋转 90° tft.fillScreen(TFT_BLACK); // 清屏为黑色 tft.setTextColor(TFT_WHITE); tft.drawString("Hello TFT_eSPI!", 40, 100); // 打印一行字 } void loop() {}

几个点顺带说明：init()执行时会顺带点亮背光（前提是你已在配置里定义了TFT_BL引脚）；setRotation()接受 0～3，分别对应四个朝向，改数字就能横竖屏切换，不用动其他坐标逻辑。如果屏幕亮了但红蓝颜色反着、或者黑白颠倒，别急着怀疑线——大概率是配置里的TFT_RGB_ORDER或TFT_INVERSION_ON/OFF没对上你的屏，文末有排查办法。

画出第一张图：矩形、圆形、文字与旋转

点亮之后就是画图。TFT_eSPI 的绘图 API 命名很直白，仪表盘常用的四个动作：

• fillRect(x, y, w, h, color)：实心矩形，面板底色、分区框全靠它；
• fillCircle(x, y, r, color)：实心圆，指示灯、圆环仪表的起点；
• drawString(str, x, y)：输出文本，配合setFont()、setTextColor(前景, 背景)换字体和配色；
• setRotation(n)：整屏旋转，仪表从竖屏改横屏不用重写布局。

examples/ 里320 x 240/、480 x 320/这些文件夹按屏宽分好了，里面有仪表、星域、贪吃蛇之类的完整示范，照着改参数就能出效果；想要抗锯齿的弧线、圆、圆角矩形，看Smooth Graphics/文件夹。

进阶玩法：Sprite 精灵图、平滑字体与触摸校准

屏能画字画框之后，真正让项目"像样"的是下面三样东西。

Sprite 精灵图：先在 RAM 里开一块离屏缓冲区，所有绘制都发生在缓冲区里，完成后一次性推上屏。好处是画面不闪烁、可以整块旋转和搬移，做仪表盘指针、滚动条这种高频局部刷新特别合适。Sprite 有 16 位、8 位、4 位、1 位几种像素格式可选，内存紧张就降位深。完整玩法看 examples/Sprite/。

Smooth Fonts 平滑字体：库自带的位图字体放大后会发虚，Smooth Fonts 是抗锯齿方案，字体以.vlw文件存放（可放 Flash、SPIFFS、LittleFS、SD 卡），字距平滑、支持 Unicode。想生成自己的字体，用 Tools/Create_Smooth_Font/ 里的工具把 TTF 转成头文件即可；现成示例在 examples/Smooth Fonts/。常用英文字体则直接收在 Fonts/ 目录。

触摸校准：前面说过 XPT2046 触摸支持是内置的，Generic/Touch_calibrate/里的校准示例跑一遍，记下几个系数，之后Extensions/Touch.cpp就能稳定读出手指坐标，做按钮和滑块。

TFT 屏点不亮、颜色发反、刷新卡顿：三个高频问题逐一排查

最后把最常见的翻车点列出来，基本覆盖新手 90% 的求助：

屏完全没反应？按这个顺序查：电源和 GND 是否接对（3.3V 屏别喂 5V）→ RST、CS、DC 三根线是否虚接 → 配置文件里的驱动宏和引脚定义是否和你的屏一致。库里专门给了两个诊断工具：Test and diagnostics/Read_User_Setup/能把当前生效的配置打印出来，TFT_ReadWrite_Test/测试显存读写，一跑便知问题在哪。

颜色红蓝颠倒、黑白反转？回到User_Setup.h：ST7735、ST7789、ILI9341 这几款屏受TFT_RGB_ORDER（TFT_RGB/TFT_BGR）影响；黑白反了就切TFT_INVERSION_ON/TFT_INVERSION_OFF。两者各试一次，别贪多。

刷新太卡？先确认没开 DMA（ESP32、ESP32-S3、RP2040、STM32 的 SPI 屏都能开，配置里有开关）；RP2040 用户直接上并口，16 位并口清屏只要几毫秒。动画类应用把变化区域放进 Sprite 里局部推屏，而不是每帧全屏重绘。ESP8266 本身算力有限，慢属正常，别硬扛。

内存怎么选、什么颜色格式？16 位 565 色是通用档，绝大多数屏用它；RP2040 并口还能切 18 位（3-3-3 格式）追求更好色阶。算一笔账：240×240 的 16 位 Sprite 约占 115KB RAM，ESP8266 上要掂量，ESP32 和 RP2040 则相对宽裕。

资源地图：遇到问题先翻哪三个目录

• docs/：PlatformIO 配置、ESP-IDF 用法、树莓派屏接线这类"装完不知道怎么配"的问题；
• examples/：按屏幕尺寸和玩法分类的完整工程，找同类抄作业；
• Fonts/ 与 User_Setups/：字体资源和硬件预设，动手前先看看有没有现成的。

一个 ESP32、一块屏、一把杜邦线，配上下面的资源，一个能看的 TFT 界面一两个晚上就能出来。接下来做什么？先跑通320 x 240/TFT_Clock/，把时间画上去，手感就来了。

【免费下载链接】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