这块屏用一句话形容就是人人都觉得接线简单但十个里有八个会遇到黑屏。标题里写着“告别黑屏”说明你已经踩进了这个坑——买了块240x320的ST7789V TFT彩屏插到Arduino UNO上编译下载一气呵成结果屏幕点亮或者根本没亮白的白、黑的黑、花的像雪花电视。我最早翻车的那次原因特别蠢背光引脚没接。没错屏通电了、数据线全对但背光不使能整个屏幕乌漆抹黑我愣是排查了半天。后来陆陆续续点亮了不同厂商的模块才把这类屏的脾气摸清楚ST7789V本身不复杂但库、供电、接线三样里任何一样含糊结果都是黑屏。这篇文章就把我从“买到屏”到“跑通Demo”的全过程拆开讲先解决怎么识别手里的芯片再给出一份可以直接抄的接线表和供电红线然后说清楚库文件到底应该怎么选、装完要改哪些配置最后按“黑屏—白屏—花屏—反色”四种现象给你一条完整的排查链路。阅读对象包括第一次摸Arduino的纯新手也包括想把显示模块快速纳入自己项目的嵌入式老手——反正核心目标就一个让这块屏在UNO上老老实实显示画面。1. 先分清屏的“芯”ST7789V与ST7735、ILI9341到底差在哪1.1 不是所有TFT都叫ST7789也不是印着ST7735就不能是ST7789做这个项目的第一步不是接线而是确认控制器型号。市面上240x320的小尺寸TFT屏幕模组上最常见的驱动芯片是ST7789V但也有相当一部分板子用的是ST7735或ILI9341甚至有商家把ST7735驱动板的库存贴上“ST7789”标签卖——反过来也有芯片实际是ST7789V、丝印却写着ST7735的奇葩板子。库的初始化指令不同驱动类型选错最常见的后果就是白屏或花屏跟接线没关系。ST7789V和ST7735最核心的差异是分辨率ST7735原生支持到128x160为主虽然可以靠偏移模拟到更高分辨率但真跑240x320会吃力ST7789V原生地址范围就是240x320还有320x240横屏并且支持18bit色深、SPI接口、RGB接口还有一部分模组把SPI和RGB做成同一个FPC座子。ILI9341则是老牌大屏驱动常用于2.4寸以上屏幕它的初始化时序跟ST7789也有差异。所以如果库里面写的是ST7735驱动碰上ST7789V屏初始化命令序列会对不上。怎么判断手头板子到底是哪颗芯片三个办法看模块背面丝印一般会印IC型号ST7789V常见印着字母“V”结尾基本就是ST7789系列。看模块PCB上的晶振和电容布局ST7789V方案通常搭配一个12MHz左右的晶振和几颗钽电容但这方法对新手不友好参考价值有限。直接上电跑两个驱动用TFT_eSPI库把驱动宏从ST7789_DRIVER切成ST7735_DRIVER各跑一次看哪次画面正常。这也是最笨但最可靠的“暴力识别法”。1.2 模块上的稳压芯片和丝印含义决定了你敢不敢接5VST7789V芯片本身是3.3V逻辑芯片但模组板上大概率已经帮你做好电平适配。买模块时多看一眼背面如果有一颗三端稳压器丝印常见AMS1117-3.3或类似编号说明模组自带5V转3.3V电路那么模块的VCC可以直接接Arduino UNO的5V如果背面干干净净没有稳压芯片模块的VCC只能接UNO的3.3V接5V大概率当场冒烟。这个坑比想象中的常见。我见过有人买了“兼容Arduino”的屏幕直接接5V烧掉回头骂屏幕垃圾——其实模块上印着工作电压3.3V只是他没看丝印。另外引脚丝印也要看懂。很多模块标注的是SCL、SDA新手一看以为是I2C就把SCL接到UNO的A5I2C时钟、SDA接到A4结果必然黑屏。实际上这种屏幕是SPI接口SCL是SPI的SCK时钟线SDA是SPI的MOSI数据线千万不能按I2C接。模块上真正的I2C接口一般是单独出现并且旁边明确写GND和VCC而不是只有5根排针。2. 接线图与供电红线UNO的5V电平是怎么安全送进3.3V屏的2.1 电源方案稳压芯片在不在决定接5V还是3V3先把供电这条线理清楚。Arduino UNO的板载3.3V输出能力有限最大可持续电流大概在150mA级别的水平由板载稳压器决定实测不同批次有差异。一块240x320的TFT模块背光全开时电流大约在40~80mA之间加上芯片自身工作电流勉强在UNO 3.3V端口的承受范围内。但如果你的UNO还同时给其他传感器供电3.3V电压就容易被拉低电压一抖屏幕就是白屏、闪屏、黑屏三选一。所以我的建议是分情况处理模块带稳压芯片直接5V接模块VCC。这样最稳背光亮、电流充足。但注意模块的IO逻辑仍是3.3V数据线不能直接怼5V这是后面电平匹配的问题。模块不带稳压芯片只能从UNO的3.3V取电同时尽量别让其他外设共享这路电源如果带动其他传感器导致电压不稳建议换成外部3.3V稳压模块独立供电地线跟UNO共地即可。模块的VCC标着3.3V但你从5V经一个二极管或电阻降压不建议压降和电流都不可控别省这个电源钱。2.2 一张可以直接抄的UNO接线表ST7789V典型SPI模组至少有6根信号线VCC、GND、CS、RESET、DC也叫RS、SCK、MOSI有的还有BLK背光、MISO。完整接线如下模块引脚接Arduino UNO引脚说明VCC5V带稳压或3.3V不带稳压电源正极先确认模组有没有稳压GNDGND电源地CSD10SPI片选低电平有效RESET / RSTD8复位引脚低电平复位DC / RSD9数据/命令选择SCK / SCLD13SPI时钟MOSI / SDAD11SPI主出从入数据线BLK / BL / LED3.3V或经限流电阻接5V背光使能一般高电平点亮MISO / SDO悬空只写不读时可以悬空简单记忆法CS/D9/D8随便你占用但SCK和MOSI尽量用D13和D11因为TFT_eSPI库在UNO上会优先使用硬件SPI引脚速度快、时序稳。如果你非要用D2、D3之类的软件SPI也能跑但刷新率会明显下降纯新手不建议自找麻烦。2.3 关于5V逻辑打进3.3V屏为什么多数人忽略也没事但严谨的话要处理Arduino UNO的SPI输出是5V电平ST7789V是3.3V芯片严格来说这是电平不匹配。理论上有烧坏芯片的风险但实际中ST7789V的IO引脚对5V输入有一定的容忍度很多模块的设计也默认你会接UNO所以大量教程是直接怼上去也确实能点亮。不过你别把侥幸当真理。严谨的做法是在MOSI、SCK、CS、DC、RESET这5根线上各串一个100~220欧姆的电阻限流或者用一颗8路电平转换模块把5V转成3.3V。我用下来最省事的方案是数据线上串220欧姆电阻。成本几分钱能有效降低过冲电压还顺带解决了一部分因为线长导致的花屏问题。注意VCC不要串限流电阻那是电源线串了会压降。另外一个容易被忽略的点模块上的MISO如果给你引出来了而你又不需要读屏别乱接。接了D12不会影响屏幕显示但如果同时挂载了SD卡等模块在同一个SPI总线上MISO信号打架就会干扰建议直接悬空。3. 库文件怎么选、去哪下、装完改什么TFT_eSPI配置实录3.1 别再去论坛求“完整库压缩包”库管理器里就有“附完整库文件”这个关键词很妙因为很多新手习惯去某论坛、某云盘下载一个“万能库.zip”解压之后往Arduino的libraries目录里一扔。这个操作我做过不止一次结果经常是编译报错、函数找不到或者装完还是一样黑屏——因为那些zip里的库版本太老连ST7789V的支持都是后来才加的。正确的姿势只有一个打开Arduino IDE的库管理器搜索TFT_eSPI。为什么要用这个库而不是另一套老的GFX图形库主要理由有三个依赖少TFT_eSPI基本是单库用法装一个就带全图形函数老GFX方案往往要装图形基础库、传感器总线库等一堆依赖新手少装一个就编译不过。对AVR优化好TFT_eSPI是专为ESP系列和AVR系列优化过的在Arduino UNO这种8位单片机上跑ST7789V性能是同类库里拔尖的。配置灵活驱动宏、引脚、SPI频率全部在配置文件里改不用改主程序排查问题更简单。顺便说一句网上有些人会推荐你下载某个机构教学扩展包说是里面带各种“xml配置”方便积木式编程。这类扩展包本身不是不能用但它面向的是那个图形化编程环境生成的东西跟Arduino C/C工程的库目录结构完全不一样你硬把它塞进libraries里库管理器根本识别不到。认准库管理器里的TFT_eSPI其他“一键库”“教学扩展包”可以先放一边。3.2 安装完成后只改一个文件User_Setup.h里到底要动哪几行首次安装好TFT_eSPI后不要急着打开示例先去改库目录下的User_Setup.h。这个文件决定库认为你接的是哪块屏、哪个引脚修改后保存即可不用改任何主程序代码。以下是一份可以直接复制粘贴的配置块针对Arduino UNO 240x320 ST7789V按我上面的接线表#define ST7789_DRIVER #define TFT_WIDTH 240 #define TFT_HEIGHT 320 #define TFT_MOSI 11 #define TFT_SCLK 13 #define TFT_CS 10 #define TFT_DC 9 #define TFT_RST 8 #define SPI_FREQUENCY 8000000注意几个细节ST7789_DRIVER是核心一定不能注释掉。TFT_eSPI库里其实支持很多驱动宏比如ST7735_DRIVER、ILI9341_DRIVER你只保留ST7789这一行即可。TFT_WIDTH和TFT_HEIGHT要按实际分辨率写。有的配置模板里默认写了别的尺寸不改会导致坐标错乱。SPI频率先设80000008MHz。Arduino UNO的AVR芯片硬件SPI上限就在这个量级强行往高了设比如27000000不一定会更快反而可能因为信号变形而花屏。点亮之后想尝试更高频率再说。改完配置文件记得重启一下Arduino IDE再编译不然库文件缓存不更新。3.3 两个要避开的常见“假配置”注释漏改和引脚冲突我在群里看过太多从头文件复制出来以后不动直接编译的案例常见症状是编译报了引脚冲突或者显示不出来。排查顺序先看User_Setup.h的这几行是否生效文件里可能有多个#define xxx_DRIVER如果没有注释掉其他驱动宏库默认还会启用IL9341之类的驱动导致初始化错乱。保留ST7789其他全部注释掉。如果同时外接SD卡模块SD卡通常也占D4/D10之类引脚片选冲突会让SPI总线数据错乱。做屏幕项目时尽量先拔掉SD卡跑通屏幕再加。4. 第一次点亮编写三色自检程序并确认240x320坐标系4.1 初始化只有两行但你自己要先搞懂坐标系TFT_eSPI的例程里初始化非常简短核心就是#include TFT_eSPI.h TFT_eSPI tft TFT_eSPI(); void setup() { tft.init(); tft.fillScreen(TFT_RED); } void loop() {}tft.init()会自动按照User_Setup.h里的配置完成初始化时序。这一步如果成功屏幕会变成纯色如果还是黑屏说明问题在硬件层往下看第5节排查。关于坐标系ST7789V本身是240x320的寻址范围宽度方向240个像素高度方向320个像素。竖屏使用时最常见的模块物理方向其逻辑坐标也对应240宽、320高当你调用tft.setRotation(1)后坐标系会变成320宽、240高相当于横屏。这里有个新手常犯的错屏幕物理竖着放非要在代码里横屏使用结果画了半天只显示半边。我的经验是先保持默认旋转方向跑通确认显示正常再玩setRotation。4.2 一个能快速验证所有信号线是否“通了”的Demo三色自检几乎是TFT项目里的标准起点原因很直接纯色填充只需要驱动芯片配合如果填充一整屏红色成功了基本说明SPI读写、初始化、颜色数据全是通的接下来花屏与否才是频率和时序层面的问题。把下面代码烧录进去#include TFT_eSPI.h TFT_eSPI tft TFT_eSPI(); void setup() { tft.init(); tft.fillScreen(TFT_RED); delay(1000); tft.fillScreen(TFT_GREEN); delay(1000); tft.fillScreen(TFT_BLUE); delay(1000); tft.fillScreen(TFT_WHITE); delay(1000); tft.setTextColor(TFT_BLACK, TFT_WHITE); tft.drawString(240x320 OK, 40, 140, 4); } void loop() {}烧录后如果能看到红绿蓝白四次整屏切换恭喜这颗屏的核心链路已经通了。注意最后一行drawString里用的字体大小为4在240x320分辨率下显示一串文本刚刚好如果要显示中文还得另做字库这一步先不展开。4.3 UNO上要有点耐心为什么刷新速度不可能“跑满”很多人在UNO上点亮ST7789V之后第一反应是“怎么这么慢”——全屏填充确实有肉眼可见的刷新过程。这不是屏的问题也不是库写得差而是UNO的ATmega328P只有8位、16MHz主频SPI数据还是从内存一个字节一个字节往屏里灌。240x320的RGB565全屏有约15万个像素点每个点2字节可刷新速度的上限很大程度上被芯片性能卡住。所以不要在UNO上追求高帧率。做菜单、状态页这类静态或慢更新界面很合适做动画、视频流场景建议直接换ESP32或STM32平台TFT_eSPI在那些平台上的DMA加速才能真正发挥。这篇文章写UNO是因为入门门槛低、社区资料多适合把SPI驱动和屏体原理吃透。5. 还在黑屏按这四条路逐级排查黑屏、白屏、花屏、反色5.1 全黑但背光正常先查初始化再看数据线先做一个分类屏幕“全黑”分两种一种是背光没亮整个屏面亮都不亮另一种是背光亮了但画面是黑的晚上看能看到屏幕泛白。如果是后者问题基本不在电源而在初始化命令没执行成功。初始化没成功的常见原因按概率排序CS、DC、RESET三根线的引脚定义跟User_Setup.h不一致。特别是DC很多库默认引脚是9如果你实际接的是7那就永远进不了数据模式。RESET引脚悬空或没接。ST7789V靠RESET引脚的低脉冲复位不接等于复位时序缺失驱动芯片可能停在未知状态。库驱动选错。比如模块实际是ILI9341或者ST7735但代码里用的是ST7789初始化命令序列完全不一样。你可以用示波器量RESET引脚在上电瞬间有没有一个明显的低脉冲没有示波器就人为在代码里加一段pinMode(8, OUTPUT); digitalWrite(8, LOW); delay(50); digitalWrite(8, HIGH);这个软件复位时序往往能救活一部分“黑屏”。5.2 白屏背光亮、无任何显示大概率是DC和CS对调了白屏是一个非常经典的现象屏幕均匀地亮像一张白纸。很多人以为这是“屏坏了”或“没初始化”实际上多半是DC和CS接反了。原因在于ST7789V是通过DC引脚区分“数据”和“命令”。如果DC和CS两根线接反初始化时命令和片选时序完全错乱芯片不会执行任何有效命令最后卡斯在某种默认状态屏幕就白着。解决方法很简单把D9和D10对应的杜邦线互换一下重试。另外一个白屏原因是上电时序。有些模块要求片选CS在上电期间保持高电平如果你的初始化代码在库初始化之前就把CS拉低了芯片会识别错误。这也解释了为什么有时候按一下RESET就突然正常了——其实是时序歪打正着。5.3 花屏和错位从频率和线材入手而不是改代码花屏分两种一种是全屏“雪花”或颜色随机跳另一种是整个画面“错位”或左右镜像。前者多是信号问题后者多是参数问题。雪花花屏先查三样东西杜邦线长度。超过15cm的杜邦线在8MHz SPI下就可能出现信号畸变特别是把SCK和MOSI两根长线并排走的时候。尽量缩短线距或者换成排线焊接。SPI频率太高。把User_Setup.h里的SPI_FREQUENCY降到4000000试一次好转就说明是频率边界问题。UNO上不需要追求高频稳定第一。电源纹波。屏幕白屏或花屏时用万用表量模块VCC是否稳定在3.3V附近电压在4.8V以下波动背光和驱动都会抽风。画面错位则大概率是初始化参数里的偏移值不对。TFT_eSPI对ST7789有两种常见屏幕偏移配置比如TFT_RGB_ORDER和TFT_INVERSION_ON等宏。如果色彩正常但画面位置歪了可以尝试在配置里加一行#define TFT_OFFSET_X 0 #define TFT_OFFSET_Y 0有些屏厂把面板窗口做了偏移官方默认值不一定适合你的批次。5.4 颜色反了RGB和BGR一次就够全屏红色显示成蓝色、绿色显示成紫色这属于色彩通道顺序问题不是接线错误。ST7789V面板的RGB子像素排列因模组厂家而异有的用RGB顺序有的用BGR顺序。在TFT_eSPI里这由User_Setup.h中的宏控制。如果你发现颜色不对劲将// 默认未定义时通常是RGB改成#define TFT_BGR保存后重新编译烧录。注意有一部分SCT7789V模块需要把TFT_INVERSION_ON或TFT_INVERSION_OFF也切换一下才能让白色更纯、黑色更黑。这两个宏在配置里都有注释改一次编译一次看效果即可。6. 点亮之后的进阶调校旋转、色彩顺序与刷新性能6.1 旋转与坐标偏移setRotation四个值到底在干吗跑通纯色自检之后你一定想把它用于实际项目这时候旋转就逃不掉了。tft.setRotation()接受0到3四个参数0和2是竖屏1和3是横屏并且每旋转90度一次。实现原理是修改ST7789V的MADCTL寄存器改变扫描方向和行列地址映射不需要重传数据。在240x320的模块上旋转会影响你的画布宽高。比如setRotation(0)时以240宽、320高绘制setRotation(1)之后要以320宽、240高来思考坐标。很多人程序里写死了宽度240转横屏后最右边一片画不进去就是这个原因。实践中我的做法是定义两个全局变量uint16_t screenW tft.width(); uint16_t screenH tft.height();旋转之后不要直接使用字面量而是用这两个变量计算坐标整个项目代码就不会因为旋转而散架。6.2 性能还能挤一挤SPI频率与局部更新策略虽然UNO上限有限但也不是毫无优化空间。如果你在冷启动时屏幕初始化正常、刷新也稳定可以试着把User_Setup.h里的SPI_FREQUENCY从8000000改到16000000观察花屏是否出现。注意ATmega328P的硬件SPI分频器未必能精确输出这个频率所以频段不同表现会有差异以实际稳定为准。另外一个更有效的优化是局部刷新。ST7789V的驱动芯片本身是一整块显存但你可以通过向Y坐标的高字节和低字节寄存器写入起始和结束地址让它只更新画面中的某个区域。TFT_eSPI里画矩形、画文字默认都会尽量做区域裁剪。如果你的界面是仪表盘那种——指针变化、数字变化其他区域几乎不动那就只重绘变化区域帧率体感能提高几倍。6.3 关于“官方库文件”的最后一件事版本和备份最后补一句关于“库文件”的执念。很多人老觉得手头有一份离线zip才放心我理解这种安全感但Arduino的库生态里离线zip反而是版本管理最差的方式——你永远不知道那份zip是哪个年份的里面驱动宏到底适配不支持ST7789V。更稳妥的办法是库管理器安装完后直接把C:\Users\你的用户名\Documents\Arduino\libraries\TFT_eSPI整个文件夹复制一份存到网盘或本地备份。万一之后实验把User_Setup.h改乱了一行命令还原就行比到处找“完整库文件”靠谱得多。另外提醒一点如果你手上的模块很可能是缩水版或者老批次跑ST7789V驱动宏白屏别急着丢弃。把ST7789_DRIVER注释掉换ST7735_DRIVER跑一遍三色自检两分钟就能排除芯片丝印错误的可能。我那块号称ST7789却怎么也点不亮的板子最后就是用ST7735驱动跑通的丝印和芯片对不上的情况在廉价模组里真不少见。点亮一块ST7789V的240x320彩屏说穿了就是“芯片认准、电源稳、线序对、库匹配”四件事。从硬件侧先判断模块有没有稳压芯片和背光使能再到软件侧选TFT_eSPI并改好User_Setup.h里的驱动宏、引脚和频率最后用三色自检做隔离测试。整个链路里最隐蔽的坑往往不是代码而是接线丝印和库版本。按这个顺序来黑屏大概率和你说再见接下来就可以放心去做你自己的界面了。 
长河君 · 2026/10/10 1:49:48 · 阅读 1.2k 告别黑屏：Arduino UNO点亮ST7789V TFT彩屏完整指南
这块屏用一句话形容就是人人都觉得接线简单但十个里有八个会遇到黑屏。标题里写着“告别黑屏”说明你已经踩进了这个坑——买了块240x320的ST7789V TFT彩屏插到Arduino UNO上编译下载一气呵成结果屏幕点亮或者根本没亮白的白、黑的黑、花的像雪花电视。我最早翻车的那次原因特别蠢背光引脚没接。没错屏通电了、数据线全对但背光不使能整个屏幕乌漆抹黑我愣是排查了半天。后来陆陆续续点亮了不同厂商的模块才把这类屏的脾气摸清楚ST7789V本身不复杂但库、供电、接线三样里任何一样含糊结果都是黑屏。这篇文章就把我从“买到屏”到“跑通Demo”的全过程拆开讲先解决怎么识别手里的芯片再给出一份可以直接抄的接线表和供电红线然后说清楚库文件到底应该怎么选、装完要改哪些配置最后按“黑屏—白屏—花屏—反色”四种现象给你一条完整的排查链路。阅读对象包括第一次摸Arduino的纯新手也包括想把显示模块快速纳入自己项目的嵌入式老手——反正核心目标就一个让这块屏在UNO上老老实实显示画面。1. 先分清屏的“芯”ST7789V与ST7735、ILI9341到底差在哪1.1 不是所有TFT都叫ST7789也不是印着ST7735就不能是ST7789做这个项目的第一步不是接线而是确认控制器型号。市面上240x320的小尺寸TFT屏幕模组上最常见的驱动芯片是ST7789V但也有相当一部分板子用的是ST7735或ILI9341甚至有商家把ST7735驱动板的库存贴上“ST7789”标签卖——反过来也有芯片实际是ST7789V、丝印却写着ST7735的奇葩板子。库的初始化指令不同驱动类型选错最常见的后果就是白屏或花屏跟接线没关系。ST7789V和ST7735最核心的差异是分辨率ST7735原生支持到128x160为主虽然可以靠偏移模拟到更高分辨率但真跑240x320会吃力ST7789V原生地址范围就是240x320还有320x240横屏并且支持18bit色深、SPI接口、RGB接口还有一部分模组把SPI和RGB做成同一个FPC座子。ILI9341则是老牌大屏驱动常用于2.4寸以上屏幕它的初始化时序跟ST7789也有差异。所以如果库里面写的是ST7735驱动碰上ST7789V屏初始化命令序列会对不上。怎么判断手头板子到底是哪颗芯片三个办法看模块背面丝印一般会印IC型号ST7789V常见印着字母“V”结尾基本就是ST7789系列。看模块PCB上的晶振和电容布局ST7789V方案通常搭配一个12MHz左右的晶振和几颗钽电容但这方法对新手不友好参考价值有限。直接上电跑两个驱动用TFT_eSPI库把驱动宏从ST7789_DRIVER切成ST7735_DRIVER各跑一次看哪次画面正常。这也是最笨但最可靠的“暴力识别法”。1.2 模块上的稳压芯片和丝印含义决定了你敢不敢接5VST7789V芯片本身是3.3V逻辑芯片但模组板上大概率已经帮你做好电平适配。买模块时多看一眼背面如果有一颗三端稳压器丝印常见AMS1117-3.3或类似编号说明模组自带5V转3.3V电路那么模块的VCC可以直接接Arduino UNO的5V如果背面干干净净没有稳压芯片模块的VCC只能接UNO的3.3V接5V大概率当场冒烟。这个坑比想象中的常见。我见过有人买了“兼容Arduino”的屏幕直接接5V烧掉回头骂屏幕垃圾——其实模块上印着工作电压3.3V只是他没看丝印。另外引脚丝印也要看懂。很多模块标注的是SCL、SDA新手一看以为是I2C就把SCL接到UNO的A5I2C时钟、SDA接到A4结果必然黑屏。实际上这种屏幕是SPI接口SCL是SPI的SCK时钟线SDA是SPI的MOSI数据线千万不能按I2C接。模块上真正的I2C接口一般是单独出现并且旁边明确写GND和VCC而不是只有5根排针。2. 接线图与供电红线UNO的5V电平是怎么安全送进3.3V屏的2.1 电源方案稳压芯片在不在决定接5V还是3V3先把供电这条线理清楚。Arduino UNO的板载3.3V输出能力有限最大可持续电流大概在150mA级别的水平由板载稳压器决定实测不同批次有差异。一块240x320的TFT模块背光全开时电流大约在40~80mA之间加上芯片自身工作电流勉强在UNO 3.3V端口的承受范围内。但如果你的UNO还同时给其他传感器供电3.3V电压就容易被拉低电压一抖屏幕就是白屏、闪屏、黑屏三选一。所以我的建议是分情况处理模块带稳压芯片直接5V接模块VCC。这样最稳背光亮、电流充足。但注意模块的IO逻辑仍是3.3V数据线不能直接怼5V这是后面电平匹配的问题。模块不带稳压芯片只能从UNO的3.3V取电同时尽量别让其他外设共享这路电源如果带动其他传感器导致电压不稳建议换成外部3.3V稳压模块独立供电地线跟UNO共地即可。模块的VCC标着3.3V但你从5V经一个二极管或电阻降压不建议压降和电流都不可控别省这个电源钱。2.2 一张可以直接抄的UNO接线表ST7789V典型SPI模组至少有6根信号线VCC、GND、CS、RESET、DC也叫RS、SCK、MOSI有的还有BLK背光、MISO。完整接线如下模块引脚接Arduino UNO引脚说明VCC5V带稳压或3.3V不带稳压电源正极先确认模组有没有稳压GNDGND电源地CSD10SPI片选低电平有效RESET / RSTD8复位引脚低电平复位DC / RSD9数据/命令选择SCK / SCLD13SPI时钟MOSI / SDAD11SPI主出从入数据线BLK / BL / LED3.3V或经限流电阻接5V背光使能一般高电平点亮MISO / SDO悬空只写不读时可以悬空简单记忆法CS/D9/D8随便你占用但SCK和MOSI尽量用D13和D11因为TFT_eSPI库在UNO上会优先使用硬件SPI引脚速度快、时序稳。如果你非要用D2、D3之类的软件SPI也能跑但刷新率会明显下降纯新手不建议自找麻烦。2.3 关于5V逻辑打进3.3V屏为什么多数人忽略也没事但严谨的话要处理Arduino UNO的SPI输出是5V电平ST7789V是3.3V芯片严格来说这是电平不匹配。理论上有烧坏芯片的风险但实际中ST7789V的IO引脚对5V输入有一定的容忍度很多模块的设计也默认你会接UNO所以大量教程是直接怼上去也确实能点亮。不过你别把侥幸当真理。严谨的做法是在MOSI、SCK、CS、DC、RESET这5根线上各串一个100~220欧姆的电阻限流或者用一颗8路电平转换模块把5V转成3.3V。我用下来最省事的方案是数据线上串220欧姆电阻。成本几分钱能有效降低过冲电压还顺带解决了一部分因为线长导致的花屏问题。注意VCC不要串限流电阻那是电源线串了会压降。另外一个容易被忽略的点模块上的MISO如果给你引出来了而你又不需要读屏别乱接。接了D12不会影响屏幕显示但如果同时挂载了SD卡等模块在同一个SPI总线上MISO信号打架就会干扰建议直接悬空。3. 库文件怎么选、去哪下、装完改什么TFT_eSPI配置实录3.1 别再去论坛求“完整库压缩包”库管理器里就有“附完整库文件”这个关键词很妙因为很多新手习惯去某论坛、某云盘下载一个“万能库.zip”解压之后往Arduino的libraries目录里一扔。这个操作我做过不止一次结果经常是编译报错、函数找不到或者装完还是一样黑屏——因为那些zip里的库版本太老连ST7789V的支持都是后来才加的。正确的姿势只有一个打开Arduino IDE的库管理器搜索TFT_eSPI。为什么要用这个库而不是另一套老的GFX图形库主要理由有三个依赖少TFT_eSPI基本是单库用法装一个就带全图形函数老GFX方案往往要装图形基础库、传感器总线库等一堆依赖新手少装一个就编译不过。对AVR优化好TFT_eSPI是专为ESP系列和AVR系列优化过的在Arduino UNO这种8位单片机上跑ST7789V性能是同类库里拔尖的。配置灵活驱动宏、引脚、SPI频率全部在配置文件里改不用改主程序排查问题更简单。顺便说一句网上有些人会推荐你下载某个机构教学扩展包说是里面带各种“xml配置”方便积木式编程。这类扩展包本身不是不能用但它面向的是那个图形化编程环境生成的东西跟Arduino C/C工程的库目录结构完全不一样你硬把它塞进libraries里库管理器根本识别不到。认准库管理器里的TFT_eSPI其他“一键库”“教学扩展包”可以先放一边。3.2 安装完成后只改一个文件User_Setup.h里到底要动哪几行首次安装好TFT_eSPI后不要急着打开示例先去改库目录下的User_Setup.h。这个文件决定库认为你接的是哪块屏、哪个引脚修改后保存即可不用改任何主程序代码。以下是一份可以直接复制粘贴的配置块针对Arduino UNO 240x320 ST7789V按我上面的接线表#define ST7789_DRIVER #define TFT_WIDTH 240 #define TFT_HEIGHT 320 #define TFT_MOSI 11 #define TFT_SCLK 13 #define TFT_CS 10 #define TFT_DC 9 #define TFT_RST 8 #define SPI_FREQUENCY 8000000注意几个细节ST7789_DRIVER是核心一定不能注释掉。TFT_eSPI库里其实支持很多驱动宏比如ST7735_DRIVER、ILI9341_DRIVER你只保留ST7789这一行即可。TFT_WIDTH和TFT_HEIGHT要按实际分辨率写。有的配置模板里默认写了别的尺寸不改会导致坐标错乱。SPI频率先设80000008MHz。Arduino UNO的AVR芯片硬件SPI上限就在这个量级强行往高了设比如27000000不一定会更快反而可能因为信号变形而花屏。点亮之后想尝试更高频率再说。改完配置文件记得重启一下Arduino IDE再编译不然库文件缓存不更新。3.3 两个要避开的常见“假配置”注释漏改和引脚冲突我在群里看过太多从头文件复制出来以后不动直接编译的案例常见症状是编译报了引脚冲突或者显示不出来。排查顺序先看User_Setup.h的这几行是否生效文件里可能有多个#define xxx_DRIVER如果没有注释掉其他驱动宏库默认还会启用IL9341之类的驱动导致初始化错乱。保留ST7789其他全部注释掉。如果同时外接SD卡模块SD卡通常也占D4/D10之类引脚片选冲突会让SPI总线数据错乱。做屏幕项目时尽量先拔掉SD卡跑通屏幕再加。4. 第一次点亮编写三色自检程序并确认240x320坐标系4.1 初始化只有两行但你自己要先搞懂坐标系TFT_eSPI的例程里初始化非常简短核心就是#include TFT_eSPI.h TFT_eSPI tft TFT_eSPI(); void setup() { tft.init(); tft.fillScreen(TFT_RED); } void loop() {}tft.init()会自动按照User_Setup.h里的配置完成初始化时序。这一步如果成功屏幕会变成纯色如果还是黑屏说明问题在硬件层往下看第5节排查。关于坐标系ST7789V本身是240x320的寻址范围宽度方向240个像素高度方向320个像素。竖屏使用时最常见的模块物理方向其逻辑坐标也对应240宽、320高当你调用tft.setRotation(1)后坐标系会变成320宽、240高相当于横屏。这里有个新手常犯的错屏幕物理竖着放非要在代码里横屏使用结果画了半天只显示半边。我的经验是先保持默认旋转方向跑通确认显示正常再玩setRotation。4.2 一个能快速验证所有信号线是否“通了”的Demo三色自检几乎是TFT项目里的标准起点原因很直接纯色填充只需要驱动芯片配合如果填充一整屏红色成功了基本说明SPI读写、初始化、颜色数据全是通的接下来花屏与否才是频率和时序层面的问题。把下面代码烧录进去#include TFT_eSPI.h TFT_eSPI tft TFT_eSPI(); void setup() { tft.init(); tft.fillScreen(TFT_RED); delay(1000); tft.fillScreen(TFT_GREEN); delay(1000); tft.fillScreen(TFT_BLUE); delay(1000); tft.fillScreen(TFT_WHITE); delay(1000); tft.setTextColor(TFT_BLACK, TFT_WHITE); tft.drawString(240x320 OK, 40, 140, 4); } void loop() {}烧录后如果能看到红绿蓝白四次整屏切换恭喜这颗屏的核心链路已经通了。注意最后一行drawString里用的字体大小为4在240x320分辨率下显示一串文本刚刚好如果要显示中文还得另做字库这一步先不展开。4.3 UNO上要有点耐心为什么刷新速度不可能“跑满”很多人在UNO上点亮ST7789V之后第一反应是“怎么这么慢”——全屏填充确实有肉眼可见的刷新过程。这不是屏的问题也不是库写得差而是UNO的ATmega328P只有8位、16MHz主频SPI数据还是从内存一个字节一个字节往屏里灌。240x320的RGB565全屏有约15万个像素点每个点2字节可刷新速度的上限很大程度上被芯片性能卡住。所以不要在UNO上追求高帧率。做菜单、状态页这类静态或慢更新界面很合适做动画、视频流场景建议直接换ESP32或STM32平台TFT_eSPI在那些平台上的DMA加速才能真正发挥。这篇文章写UNO是因为入门门槛低、社区资料多适合把SPI驱动和屏体原理吃透。5. 还在黑屏按这四条路逐级排查黑屏、白屏、花屏、反色5.1 全黑但背光正常先查初始化再看数据线先做一个分类屏幕“全黑”分两种一种是背光没亮整个屏面亮都不亮另一种是背光亮了但画面是黑的晚上看能看到屏幕泛白。如果是后者问题基本不在电源而在初始化命令没执行成功。初始化没成功的常见原因按概率排序CS、DC、RESET三根线的引脚定义跟User_Setup.h不一致。特别是DC很多库默认引脚是9如果你实际接的是7那就永远进不了数据模式。RESET引脚悬空或没接。ST7789V靠RESET引脚的低脉冲复位不接等于复位时序缺失驱动芯片可能停在未知状态。库驱动选错。比如模块实际是ILI9341或者ST7735但代码里用的是ST7789初始化命令序列完全不一样。你可以用示波器量RESET引脚在上电瞬间有没有一个明显的低脉冲没有示波器就人为在代码里加一段pinMode(8, OUTPUT); digitalWrite(8, LOW); delay(50); digitalWrite(8, HIGH);这个软件复位时序往往能救活一部分“黑屏”。5.2 白屏背光亮、无任何显示大概率是DC和CS对调了白屏是一个非常经典的现象屏幕均匀地亮像一张白纸。很多人以为这是“屏坏了”或“没初始化”实际上多半是DC和CS接反了。原因在于ST7789V是通过DC引脚区分“数据”和“命令”。如果DC和CS两根线接反初始化时命令和片选时序完全错乱芯片不会执行任何有效命令最后卡斯在某种默认状态屏幕就白着。解决方法很简单把D9和D10对应的杜邦线互换一下重试。另外一个白屏原因是上电时序。有些模块要求片选CS在上电期间保持高电平如果你的初始化代码在库初始化之前就把CS拉低了芯片会识别错误。这也解释了为什么有时候按一下RESET就突然正常了——其实是时序歪打正着。5.3 花屏和错位从频率和线材入手而不是改代码花屏分两种一种是全屏“雪花”或颜色随机跳另一种是整个画面“错位”或左右镜像。前者多是信号问题后者多是参数问题。雪花花屏先查三样东西杜邦线长度。超过15cm的杜邦线在8MHz SPI下就可能出现信号畸变特别是把SCK和MOSI两根长线并排走的时候。尽量缩短线距或者换成排线焊接。SPI频率太高。把User_Setup.h里的SPI_FREQUENCY降到4000000试一次好转就说明是频率边界问题。UNO上不需要追求高频稳定第一。电源纹波。屏幕白屏或花屏时用万用表量模块VCC是否稳定在3.3V附近电压在4.8V以下波动背光和驱动都会抽风。画面错位则大概率是初始化参数里的偏移值不对。TFT_eSPI对ST7789有两种常见屏幕偏移配置比如TFT_RGB_ORDER和TFT_INVERSION_ON等宏。如果色彩正常但画面位置歪了可以尝试在配置里加一行#define TFT_OFFSET_X 0 #define TFT_OFFSET_Y 0有些屏厂把面板窗口做了偏移官方默认值不一定适合你的批次。5.4 颜色反了RGB和BGR一次就够全屏红色显示成蓝色、绿色显示成紫色这属于色彩通道顺序问题不是接线错误。ST7789V面板的RGB子像素排列因模组厂家而异有的用RGB顺序有的用BGR顺序。在TFT_eSPI里这由User_Setup.h中的宏控制。如果你发现颜色不对劲将// 默认未定义时通常是RGB改成#define TFT_BGR保存后重新编译烧录。注意有一部分SCT7789V模块需要把TFT_INVERSION_ON或TFT_INVERSION_OFF也切换一下才能让白色更纯、黑色更黑。这两个宏在配置里都有注释改一次编译一次看效果即可。6. 点亮之后的进阶调校旋转、色彩顺序与刷新性能6.1 旋转与坐标偏移setRotation四个值到底在干吗跑通纯色自检之后你一定想把它用于实际项目这时候旋转就逃不掉了。tft.setRotation()接受0到3四个参数0和2是竖屏1和3是横屏并且每旋转90度一次。实现原理是修改ST7789V的MADCTL寄存器改变扫描方向和行列地址映射不需要重传数据。在240x320的模块上旋转会影响你的画布宽高。比如setRotation(0)时以240宽、320高绘制setRotation(1)之后要以320宽、240高来思考坐标。很多人程序里写死了宽度240转横屏后最右边一片画不进去就是这个原因。实践中我的做法是定义两个全局变量uint16_t screenW tft.width(); uint16_t screenH tft.height();旋转之后不要直接使用字面量而是用这两个变量计算坐标整个项目代码就不会因为旋转而散架。6.2 性能还能挤一挤SPI频率与局部更新策略虽然UNO上限有限但也不是毫无优化空间。如果你在冷启动时屏幕初始化正常、刷新也稳定可以试着把User_Setup.h里的SPI_FREQUENCY从8000000改到16000000观察花屏是否出现。注意ATmega328P的硬件SPI分频器未必能精确输出这个频率所以频段不同表现会有差异以实际稳定为准。另外一个更有效的优化是局部刷新。ST7789V的驱动芯片本身是一整块显存但你可以通过向Y坐标的高字节和低字节寄存器写入起始和结束地址让它只更新画面中的某个区域。TFT_eSPI里画矩形、画文字默认都会尽量做区域裁剪。如果你的界面是仪表盘那种——指针变化、数字变化其他区域几乎不动那就只重绘变化区域帧率体感能提高几倍。6.3 关于“官方库文件”的最后一件事版本和备份最后补一句关于“库文件”的执念。很多人老觉得手头有一份离线zip才放心我理解这种安全感但Arduino的库生态里离线zip反而是版本管理最差的方式——你永远不知道那份zip是哪个年份的里面驱动宏到底适配不支持ST7789V。更稳妥的办法是库管理器安装完后直接把C:\Users\你的用户名\Documents\Arduino\libraries\TFT_eSPI整个文件夹复制一份存到网盘或本地备份。万一之后实验把User_Setup.h改乱了一行命令还原就行比到处找“完整库文件”靠谱得多。另外提醒一点如果你手上的模块很可能是缩水版或者老批次跑ST7789V驱动宏白屏别急着丢弃。把ST7789_DRIVER注释掉换ST7735_DRIVER跑一遍三色自检两分钟就能排除芯片丝印错误的可能。我那块号称ST7789却怎么也点不亮的板子最后就是用ST7735驱动跑通的丝印和芯片对不上的情况在廉价模组里真不少见。点亮一块ST7789V的240x320彩屏说穿了就是“芯片认准、电源稳、线序对、库匹配”四件事。从硬件侧先判断模块有没有稳压芯片和背光使能再到软件侧选TFT_eSPI并改好User_Setup.h里的驱动宏、引脚和频率最后用三色自检做隔离测试。整个链路里最隐蔽的坑往往不是代码而是接线丝印和库版本。按这个顺序来黑屏大概率和你说再见接下来就可以放心去做你自己的界面了。