企业官网建设流程全解析

简介：本资源是一套专为ESP32-S3平台适配LVGL v9图形库的SPI LCD驱动代码集合，面向嵌入式开发工程师、物联网项目开发者及LVGL初学者，解决多型号屏幕在ESP-IDF环境下快速移植与稳定显示的核心痛点。压缩包共13个文件（29KB），涵盖核心驱动源码（lcd_lvgl.c）、硬件抽象层头文件（config.h）、构建配置（CMakeLists.txt、sdkconfig、idf_component.yml）、开发环境支持（.vscode配置）、项目说明（README.md）及分区表（partitions.csv）等关键组件，结构清晰、开箱即用。已有950人学习下载，显著降低ST7789/ST7735/ST7796/ILI9341/ILI9488等主流SPI屏的LVGL接入门槛。用户可直接复用完整驱动框架，快速验证不同分辨率屏幕（如135×240、240×320、320×480）下的GUI渲染效果，并基于现有结构灵活扩展触摸、DMA加速或自定义控件，大幅提升IoT设备人机交互开发效率。

1. 项目概述与方案选择

做嵌入式 UI 开发的朋友应该都有这种感觉：大部分小屏项目最后都绕不开 ESP32S3 和 LVGL 这套组合。ESP32S3 本身带 PSRAM、支持 RGB 接口的芯片，性能足够跑 LVGL 动画，而 LVGL9 相对 8.x 在渲染架构上做了不少调整，对圆形、阴影、多字体渲染更友好。如果把屏幕再锁定到 SPI 接口的常见 TFT 屏，比如 ST7789、ST7735、ST7796、ILI9341、ILI9488，会碰到的第一道坎就是：网上代码大多是 ESP-IDF + 老版 LVGL，或者是 Arduino 平台直刷 TFT-eSPI，真正基于 LVGL9 原生框架写一套能通吃这些控制器的驱动并不常见。所以这篇内容我打算把自己的移植过程和踩坑记录整理出来，重点放在代码结构、分辨率适配、DMA 优化和问题排查上。

这套方案适合谁？如果你手里同时有好几块不同尺寸的 SPI 屏，想用一套代码快速切换，或者正在从 LVGL8 升级到 LVGL9，又或者只想要一份能直接复制的底层驱动逻辑，那么下面的内容应该能帮你少走很多弯路。ES32S3 的 SPI 外设资源充足，加上 LVGL9 自带的多缓冲机制，最终 UI 流畅度是可以做到非常顺滑的。不过要注意，LVGL9 的驱动接口和 8.3 之前有差异，如果直接把旧版 flush 回调搬过来会编译报错，这也是很多新手卡住的地方。

1.1 为什么选 ESP32S3 + LVGL9 + SPI 屏

先聊聊硬件选型逻辑。ESP32S3 相比 ESP32 和 ESP32C3，最大的优势是内置了 PSRAM（Octal SPI PSRAM 可选），这意味着 LVGL 的帧缓冲可以放心地放在 PSRAM 里，不会挤压内部 SRAM。对于 320x240 的 RGB565 全屏缓冲，一个 buffer 就要 150KB，如果不用 PSRAM 根本没戏。S3 的 CPU 主频 240MHz，带 SIMD 指令加速，适合图形运算。另外它还有 3 个 SPI 控制器，其中一个可以专门留给 LCD，其他外设不受干扰。

LVGL9 在渲染架构上把 draw buffer、draw unit 分得更细，支持了 SW 渲染和 GPU 加速接口。对应到 SPI LCD 场景，LVGL9 的 flush_cb 签名比 8.x 增加了一个参数，传入的是lv_display_t *，而不是之前的lv_disp_drv_t *，这个改动是初学者最容易踩的坑。LVGL9 还引入了lv_display_set_buffers来管理多缓冲，替代了 8.x 的lv_disp_draw_buf_init。所以代码迁移时不能只改函数名，很多结构体字段也不一样了。

选择 SPI 接口而不是 RGB/8080 并口的理由也很直白：SPI 屏便宜、引脚少、Wiring 简单，适合做小尺寸产品原型。RGB 屏虽然刷新快，但需要占用大量 GPIO 和 PSRAM 带宽，对于 4 寸以下屏幕来说完全没必要。SPI 接口在 40MHz 时钟下，320x240 全屏刷新大约 18ms 到 20ms，加上 LVGL 的局部刷新机制，实际 UI 体验并不会觉得卡。

1.2 常见 LCD 控制器差异与选型参考

市面上常见的 SPI LCD 控制器有 ST7735、ST7789、ILI9341、ST7796、ILI9488，还有 GC9A01、RM67162 等，但前面五款是出货量最大的。它们都是 SPI 接口，命令集相似，但初始化序列、分辨率、扫描方向、偏移值都不一样。

选型时要注意几个坑。第一是 ILI9488 用的是 3-wire SPI 还是 4-wire SPI，大部分模块是 4-wire，但有些板子把 DC 脚砍了，需要用 9-bit 命令模式。第二是 ST7789 的偏移值，不同厂商的模块虽然控制器相同，但 framebuffer 起始地址可能不同，导致显示内容整体偏移。第三是 ST7735 有多个版本（R0/R1/B1/B2），初始化序列不同，不能一概而论。我建议在设计驱动层时，把控制器型号、分辨率、偏移量、扫描方向都做成可配置结构体，不要写死在函数里，这样换屏时只需要改一个配置表。

2. 硬件连接与引脚规划

2.1 ESP32S3 SPI 外设与引脚映射

ESP32S3 内部有 3 个 SPI 控制器：SPI0/SPI1 用于 Flash，SPI2 和 SPI3 可供用户使用。在 Arduino 环境下，通常用SPI2_HOST或FSPI（即SPI2）来驱动 LCD，这样可以避免和 Flash 的 SPI 抢占总线。在 ESP-IDF 下可以用spi_bus_initialize初始化 SPI2_HOST，然后spi_bus_add_device挂载 LCD 设备。

引脚方面要注意，ESP32S3 的 GPIO 矩阵非常灵活，理论上任意 GPIO 都可以映射到 SPI 信号，但有些引脚是 strapping pin（比如 GPIO0、GPIO3、GPIO46），上电时序会影响启动模式，建议避开。另外 LCD 的时钟线最好使用支持高速输出的 GPIO，避免跨 IO 域引起的信号质量问题。常用推荐：SCLK 接 GPIO12，MOSI 接 GPIO11， DC 接 GPIO10，CS 接 GPIO9，RST 接 GPIO8，BL 接 GPIO7。这只是示例，实际根据板子调整即可。

高速 SPI 走线时，在 SCLK 和 MOSI 上串联 22Ω 到 33Ω 的电阻可以有效抑制过冲和振铃，特别是在杜邦线连接的情况下。如果屏幕排线较长，CLK 频率不要一上来就调到 80MHz，先从 40MHz 开始，用逻辑分析仪观察波形，再逐步提高。

2.2 6针SPI与标准接法

很多 ESP32S3 开发板配套的屏幕是 6 针 SPI 接口：GND、VCC（3.3V）、SCL、SDA、RES（或 RST）、DC，有的还会带 CS 和 BLK，但通常 6 针指的是 GND/VCC/SCL/SDA/RST/DC，CS 直接接地或由板载电路固定拉低。这种模块在接 ESP32S3 时，只需要把 CS 引脚接 GND 或者一个 GPIO 并默认拉低。

需要注意，有些 6 针屏的命名是“SPI”，但 SDA 是双向的，如果控制器支持 reads 操作，比如读取 ID、读取像素，SDA 需要设置为输入。大多数情况下我们只写不读，所以直接接 MOSI 即可。如果后续想读 ID 自动识别控制器，就需要把 SDA 接一个能双向切换的 GPIO。

接线范例：

2.3 硬件片选与软件片选的选择

SPI 总线上如果只挂一个 LCD，CS 可以选择固定接地，省去一个 GPIO。但在实际工程里，建议仍然用 GPIO 控制 CS，这样未来扩展触摸屏、SD 卡或第二个屏幕时，不需要改动硬件。

硬件片选（HSPI/SPI 控制器自动拉 CS）的优点是时序准确，CS 信号和时钟同步，软件层面不需要频繁操作 CS 引脚，尤其在 DMA 传输时，硬件 CS 能保证整个事务的完整性。软件片选（GPIO 手动拉低/拉高）更灵活，但对时序要求高的场景可能出现 CS 提前拉高或滞后拉低的情况。LVGL 刷新数据量很大，每帧可能多次调用 spi_transfer，如果 CS 时序不对，屏幕边缘会出现杂点。

我的建议：优先使用硬件片选。ESP-IDF 里配置spi_device_interface_config_t时设置spics_io_num为实际引脚，让驱动接管 CS。如果使用 Arduino 架构下的 LCD 库，通常也是库内部自己管理 CS，很少需要手动操作。

2.4 背光、复位与触摸引脚处理

背光引脚（BLK / LEDA）不只是接 3.3V 那么简单。如果让你通过 PWM 调节屏幕亮度，必须把 BLK 接到支持 LEDC PWM 的 GPIO，比如 GPIO7。ESP32S3 的 LEDC 支持多路 PWM，可以在ledcSetup和ledcAttachPin中配置。我在项目里发现，很多 SPI 屏背光电路不带限流电阻，直接 3.3V 供电时最大亮度可能偏高，长久使用会加速 LED 老化，最好接一个 100Ω 到 330Ω 的电阻，或者通过 PWM 默认 70% 占空比控制。

复位引脚 RST 在初始化流程中需要先拉低至少 10ms，再拉高，并且等待 120ms 以上再发送初始化命令。很多 LCD 模块的 RST 和 ESP32S3 的 EN 共用，导致屏幕初始化时机与 MCU 启动竞争，容易出现白屏。推荐使用独立 GPIO 控制 RST，即使模块要求直接接 MCU RST，也要在代码中增加延时等待。

触摸屏是另一个容易忽略的点。SPI 触摸（如 XPT2046）可以直接挂在同一 SPI 总线上，用不同的 CS 片选。LVGL9 对输入设备的接口也有调整，如果触摸控制器的坐标轴方向和屏幕旋转方向不一致，会出现触摸点反过来或者镜像的问题，这个在调试时单独处理。

3. LVGL9 与 LCD 驱动移植

3.1 LVGL9 配置关键项

LVGL9 的配置文件仍然是lv_conf.h，但版本更新后很多宏有变化。在lv_conf.h里至少需要确认以下几个关键项：

• LV_COLOR_DEPTH：一般设置为 16，对应 RGB565。
• LV_MEM_SIZE：如果不用操作系统，分配 LVGL 内部堆内存，建议 64KB 以上；如果用了 FreeRTOS，可以采用自定义分配方式。
• LV_DEF_REFR_PERIOD：刷新周期，默认 30ms，如果动画流畅度要求高，可以改为 16ms，但会增加 CPU 占用。
• LV_USE_LOG：开发期间打开日志，发布时关闭。
• LV_USE_DRAW_SW和LV_DRAW_SW_SUPPORT_GPU：SW 渲染必须开启，GPU 可以先不启用。

LVGL9 的显示设备创建方式变成了lv_display_create，并且用lv_display_set_buffers配置 draw buffer。注意，LVGL9 要求 draw buffer 地址对齐到 4 字节，如果使用 PSRAM，最好也做 8 字节或者 16 字节对齐。一个常用的做法是使用heap_caps_malloc分配 PSRAM 内存，并指定MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT。

3.2 编写 SPI LCD 驱动层

在 ESP-IDF 裸环境下，我们需要实现 LVGL 的回调：flush_cb。LVGL9 中的原型是：

void my_disp_flush(lv_display_t *disp, const lv_area_t *area, uint8_t *px_map)

内部逻辑：如果使用 DMA 则异步发送，在发送完成后调用lv_display_flush_ready(disp)。LVGL9 不再使用lv_disp_flush_ready，函数名变了，如果忽略会导致流程卡死。

一个基础实现：

static void lcd_flush_cb(lv_display_t *disp, const lv_area_t *area, uint8_t *px_map) { // 设置显示区域 lcd_set_window(area->x1, area->y1, area->x2, area->y2); size_t len = (area->x2 - area->x1 + 1) * (area->y2 - area->y1 + 1) * 2; // 发送像素数据，DMA方式 spi_transfer_with_dma(lcd_spi, px_map, len, lcd_flush_done_cb, disp); }

lcd_set_window需要根据控制器寄存器地址设置列地址和行地址。ST7789 通常使用CASET(0x2A) 和RASET(0x2B)，RA8876 等略有不同，但大多兼容。

DMA 完成回调中调用：

static void lcd_flush_done_cb(void *arg) { lv_display_flush_ready((lv_display_t *)arg); }

要注意，DMA 传输的是外部 PSRAM 的内存，ESP32S3 的 SPI DMA 可以直接访问 PSRAM，但如果 buffer 放在内部 RAM 会更稳定。如果 PSRAM 带宽和 FS 缓存冲突，可能导致偶发花屏。遇到这种情况，可以开双缓冲，让 LVGL 将渲染缓冲区定义在内部 SRAM，PSRAM 仅存放图像资源。

3.3 初始化序列与控制器差异

不同控制器的初始化序列是驱动移植中最容易出问题的地方。完整代码太长，这里给出 ST7789 的典型序列片段，其他控制器基本类似，只是命令参数不同：

static const uint8_t st7789_init[] = { 0x01, 0x00, // SWRESET 0x11, 0x00, // SLPOUT 0x36, 0x01, 0x00, // MADCTL 0x3A, 0x01, 0x05, // COLMOD 16bit 0xB2, 0x05, 0x0C, 0x0C, 0x00, 0x33, 0x33, // PORCTRL 0xB7, 0x01, 0x35, // GCTRL 0xBB, 0x01, 0x19, // VCOMS 0xC0, 0x01, 0x2C, // LCMCTRL 0xC2, 0x01, 0x01, // VDVVRHEN 0xC3, 0x01, 0x12, // VRHS 0xC4, 0x01, 0x20, // VDVS 0xC6, 0x01, 0x0F, // FRCTRL2 0xD0, 0x02, 0xA4, 0xA1, // PWCTRL1 0xE0, 15, ..., // PVGAMCTRL 0xE1, 15, ..., // NVGAMCTRL 0x13, 0x00, // NORON 0x29, 0x00, // DISPON };

初始化命令的发送顺序不能乱。尤其是SLPOUT后需要延时 120ms 以上，DISPON前最好再延时 20ms。ST7735 的初始化序列多了FRMCTR1、FRMCTR2、INVCTR等寄存器，而且分辨率不同，偏移值不同。ILI9341 需要设置PIXFMT(0x3A) 为 0x55（RGB565），ILI9488 则要设置为 0x66（RGB666）。

还有个坑：部分 ST7789 屏幕在发完SLPOUT和DISPON后，如果不对MADCTL设置方向，默认的扫描方向是从左上角开始，但有些厂商的屏幕在 PCB 上翻转了面板，实际情况可能是上下颠倒。这时需要调整MADCTL的 BIT7（MY）和 BIT6（MX）。

3.4 DMA 与双缓冲加速

DMA 是 SPI LCD 流畅运行的关键。ESP32S3 的 SPI2 支持 DMA 传输，只需要在spi_bus_initialize时设置.dma_channel = SPI_DMA_CH_AUTO，然后在传输描述符中传入 buffer 即可。DMA 传输的 buffer 要求 32-bit 对齐，LVGL 的 draw buffer 可以使用lv_display_set_buffers传入对齐地址。

双缓冲模式：LVGL9 允许设置两个 draw buffer，渲染时一个 buffer 正在被 DMA 发送，另一个 buffer 可以同时渲染下一帧，从而做到“渲染和传输并行”。这种方式对 SPI LCD 的效果提升非常明显，尤其在大分辨率屏幕上。

static lv_color_t buf1[LCD_BUF_LEN]; static lv_color_t buf2[LCD_BUF_LEN]; lv_display_set_buffers(disp, buf1, buf2, LCD_BUF_LEN * sizeof(lv_color_t), LV_DISPLAY_RENDER_MODE_PARTIAL);

LCD_BUF_LEN的计算需要根据渲染模式调整。如果使用 PARTIAL 模式，缓冲区大小可以设为屏幕行数的几倍，比如 100 行；如果使用 FULL 模式，则需要整幅画面大小的 buffer，占用内存大但渲染效率高。针对 240x320 的 RGB565，整帧 buffer 为 150KB，两个就是 300KB，只能放在 PSRAM。ESP32S3 带 8MB PSRAM 的模组很便宜，建议选择带 PSRAM 的型号。

使用 DMA 后，刷新回调中不要直接等待发送完成，要配合回调函数。LVGL9 的lv_display_flush_ready必须在 DMA 发送结束后调用，如果在发送前调用，LVGL 会认为 buffer 已经可用，下一帧渲染直接覆盖未发送完的数据，导致画面撕裂。

4. 分辨率适配与显示效果优化

4.1 常见分辨率与面板参数配置

SPI LCD 由于功耗和偏光片设计，分辨率跨度很大，常见的有 128x160、240x240、240x320、320x480。在 LVGL9 中创建显示设备时，需要明确物理分辨率：

lv_display_t *disp = lv_display_create(hor_res, ver_res);

如果屏幕模块是 240x320，但你把它旋转了 90 度，可以在驱动层通过修改MADCTL实现硬件旋转，也可以让 LVGL 软件旋转。硬件旋转更快，LVGL 只需要知道旋转后的逻辑分辨率。但如果把 LVGL 设置为软件旋转（通过lv_display_set_rotation），每次刷新前 LVGL 会在内部做像素坐标转换，CPU 开销较大。

在整机设计中，我习惯把 LCD 的初始方向固定为硬件横屏，然后通过 LVGL 的lv_display_set_rotation只做 0/90/180/270 的旋转，这样可以在不改屏幕布局的情况下适配不同 UI 方向。但注意，SPI 屏的 RAM 通常只有一帧大小，硬件旋转只是改变了扫描方向，不会改变 RAM 地址映射，所以偏移量也要跟着调整。部分控制器（如 ILI9341）的MADCTL支持行列交换，配合宽度高度设置，可以做到简单旋转。

4.2 偏移量计算

ST7789 的显示区域覆盖 240x320，但某些 240x240 的屏幕实际只有 240x240 可显示，控制器内部仍然寻址 240x320，所以需要通过VSCRDEF或者MADCTL加偏移。另外许多 1.54 英寸屏幕内部模组设计在 RAM 中偏移 0 或 80 等，需要对照模组手册。

一个通用方法是先用纯色刷新全屏，观察边缘是否有黑边或者内容偏移。然后根据实际显示位置调整偏移量。我封装了一个配置结构体：

typedef struct { uint8_t lcd_model; uint16_t width; uint16_t height; int16_t offset_x; int16_t offset_y; uint8_t madctl; bool rgb_order; } lcd_panel_config_t;

在lcd_set_window中加上偏移量，所有坐标都统一加偏移值。这样当换屏时，只需修改配置表。

4.3 RGB565 与 RGB666 的问题

ST7735、ST7789、ILI9341 基本都支持 RGB565，这是 LVGL 默认的颜色格式，直接传输即可。ILI9488 虽然也支持 RGB565 模式，但很多模组出厂默认是 RGB666，并且因为 SPI 只有 8bit/16bit 数据位宽，RGB666 需要 3 字节表示 2 像素，传输效率低。如果驱动 ILI9488 时把 LVGL 颜色深度设为 16 位，初始化命令里的COLMOD(0x3A)必须设置为0x55（RGB565），否则颜色会发绿或发白。

我建议所有屏统一使用 RGB565，哪怕 ILI9488 的色深标称 18bit，在 UI 设计上影响不大，还能提高刷新速度。如果追求 ILI9488 的高色彩，就需要把 LVGL 的LV_COLOR_DEPTH改成 18，但 ESP32S3 的 SW 渲染对 18bit 的优化不如 16bit，且 DMA 传输字节数变多，性能受损。

4.4 性能调优建议

LVGL9 在 SPI LCD 上的性能瓶颈主要在三个方面：像素数据传输、SW 渲染、刷新区域计算。

像素传输优化思路：提高 SPI 时钟、使用 DMA、使用双缓冲、减小总线切换次数。在 SPI 时钟 80MHz 下，RGB565 数据传输速率约 10MB/s，320x480 全屏数据为 300KB，全屏刷新大约 30ms。如果只做局部刷新，LVGL 会把脏区域打包成多个小区域刷新，实际流畅度反而更好。

SW 渲染优化：LVGL9 默认的 SW 渲染器带 SIMD 指令，但我们可以进一步开启LV_DRAW_SW_DRAW_UNIT_ALIGNED之类的选项，让地址对齐。此外，避免使用过多阴影、模糊和半透明图层，这些特效每次刷新都会消耗大量 CPU。SD 卡图片解码建议使用 PNG 或者 JPEG 库，但图片解码也要占用 CPU，如果只是简单图标，建议转成 C 数组并仅保留需要的尺寸。

刷新区域优化：LVGL 会通过area回调告诉驱动需要刷新的区域，我们可以在 flush 回调里做一次区域裁剪。如果多个小区域相邻，可以考虑合并成一个大的 bounding box，减少CASET/RASET设置次数，但代价是可能多传一些无用像素。这需要在传输量和命令次数之间取平衡。通常在 UI 交互密集时，区域合并能提升 10% 到 20% 的流畅度。

5. 常见问题排查与实战经验

5.1 白屏、黑屏、花屏排查顺序

白屏是最常见的。一开始不要查代码，先检查硬件：VCC 是否 3.3V，背光是否供电，RST 是否有复位波形，DC 是否正常切换。然后用逻辑分析仪或示波器抓 SPI 的 CS、SCK、MOSI 三个信号，确认代码是否真的在发送数据。

如果 SPI 波形正常但仍白屏，多半是初始化序列不完整或者时序不正确。ST7789 在SLPOUT后至少等待 120ms，否则后续命令被忽略；DISPON必须放在最后。有些初始化序列顺序错误会导致屏一直处于 sleep 状态，显示黑屏。

花屏一般是CASET/RASET设置错误，或者屏幕 RAM 行列映射方向与实际控制器不一致。比如 ST7789 在 240x320 面板上设置lcd_set_window(0,0,239,319)，但实际驱动 IC 是 320x240 的排列，导致写入的数据错位，出现条形花屏。可以先刷纯色屏测试，逐步缩小问题范围。

还有一个隐藏问题：LPCLK（MCLK）引脚未连接。部分 IPS 屏的模组需要外部提供像素时钟（通常由控制器内部产生，但某些模块的 DSI/MCLK 引出一根悬空线），如果没有正确配置会导致花屏或完全无显示。这种情况相对少见，但遇到死活用初始化代码都调不好时，检查一下模块原理图。

5.2 颜色错乱与字节序问题

显示出来颜色不对，最常见的原因是颜色高低字节顺序反了。RGB565 在 SPI 传输中，一般是高字节在前（Default byte order = Big Endian? 不一定）。ST7789 的COLMOD0x05 是 16bit/pixel，数据格式默认为RRR RRR GG GGGG GGG BBB BBB，当数据通过 SPI 8bit 模式发送时，先发高字节，再发低字节。如果你的驱动先发了低字节，颜色会完全错乱，红蓝互换等。

解决办法：在spi_transaction_t中如果使用 16bit 模式，需要配置rx_buffer和tx_buffer的对齐；如果使用 8bit 模式手动发送，则在循环中发送高字节再低字节。或者在屏幕初始化时通过MADCTL的 BGR 位（BIT3）控制 RGB/BGR 顺序，如果你的屏幕本身是 BGR 排列，需要把该位设为 1。如果你使用的是 LVGL 的 RGB565 图像，但屏幕刷新后颜色偏紫偏蓝，就优先检查 BGR 位。

另一个坑是 PSRAM 内存和 DMA 描述符地址缓存不一致。ESP32S3 有 cache，SPI DMA 读取 PSRAM 数据时，如果 cache 没有回写（writeback），读取到的可能是旧数据，导致部分区域颜色异常。解决方法是使用esp_cache_msync对 buffer 做一致性同步。这个在 ESP-IDF 5.x 中尤其重要：

esp_cache_msync((void *)px_map, len, ESP_CACHE_MSYNC_FLAG_DIR_M2C);

在 LVGL flush 回调发送数据前，加上这句话可以避免奇怪的显示残影。

5.3 闪烁与撕裂

闪烁有两个来源：背光 PWM 频率过低，或者渲染/刷屏频率不匹配。背光 PWM 频率最好设置 1kHz 以上，否则人眼会感知到闪烁。LVGL 的刷新周期和 SPI 传输周期如果不对称，也可能出现屏闪。可以试着把LV_DEF_REFR_PERIOD调整为比一帧刷屏时间稍大的值，比如屏幕全刷需要 20ms，LV_DEF_REFR_PERIOD设置 20ms 或 22ms。

撕裂是因为 LVGL 渲染和 SPI 传输不同步，后一帧数据覆盖了前一帧未发送完的 buffer。双缓冲模式下通常能解决，但要注意 LVGL 只有在lv_display_flush_ready被调用之后才会复用 buffer。如果你的 DMA 回调实现正确，撕裂基本不会发生。如果仍然有撕裂，可以在 flush 函数里增加一个“忙等待”信号量：当上一帧 DMA 还没完成时，下一帧 flush 等待。

SPI LCD 没有 TE 信号（Tearing Effect Output）时，很难做到绝对无撕裂。部分 ST7789 支持 TE 引脚，可以配置为输出扫描同步信号，再配合 LVGL 的 vsync 机制。但在实际项目中，双缓冲加适当刷新周期已经能让人眼忽略撕裂。

5.4 触摸与显示坐标不一致

这是一个常见的体验问题。触摸屏的 X 轴对应屏幕的宽还是高，取决于触摸面板安装方向和 SPI 初始化时的扫描方向。LVGL9 输入设备接口同样发生变化，需要在indev_set_read_cb中注册读取函数，然后在读取时做坐标转换。

举例：如果屏幕是 240x320 竖屏，触摸原始坐标范围是 0~4095（XPT2046），需要先根据触摸面板宽高比例换算到屏幕像素坐标，再进行映射。如果你的屏幕在初始化时使用了MADCTL旋转，那么触摸坐标的 X 可能需要映射到 LCD 的 Y。我的常用做法是写一个touch_remap函数，用两个结构体分别记录屏幕尺寸和触摸面板方向，然后根据旋转标志做四次映射组合。

一些廉价触摸屏的 XPT2046 在读取时会因为 SPI 时钟太快出现噪声，导致坐标跳变。解决方案是在 SPI 驱动触摸设备时降低时钟到 1MHz~2MHz，并在代码里加滤波（取多次采样平均值或中值滤波）。

5.5 一套代码兼容多块屏幕的驱动封装

把上面所有经验整合起来，最终驱动层应该是完全数据驱动的。我用了一个lcd_panel_t结构体，包含：

• 控制器型号枚举
• 初始化命令表指针
• 分辨率、偏移值、方向
• flush 函数指针（用于不同颜色模式）
• 自定义参数

这样在应用层只需要选择屏幕型号：

const lcd_panel_t panel = { .model = LCD_ST7789, .width = 240, .height = 240, .offset_x = 0, .offset_y = 0, .madctl = 0x00, .init_seq = st7789_init_seq, }; lcd_panel_init(&panel);

这种封装的好处是，当产品切换不同供应商的屏幕时，不用改动 UI 层逻辑，只需要修改配置。如果屏幕是同控制器但偏移量不同，甚至可以直接用运行时修改offset_x的方式调试，不用反复编译烧录。

6. 最后再说几点

这套方案我在实际项目中跑了将近半年，前后换过四款不同控制器的屏，从 ST7735 到 ILI9488 都测过。整体下来最大的体会是：SPI LCD 的驱动并不复杂，难的是把 LVGL9 的新接口、DMA 缓冲、面板差异这三个变量同时处理好。如果你严格按照上面的思路封装，后续调新屏的时间基本能压缩到半天以内。

有几个小建议送给准备入坑的朋友。第一，开发初期先把屏幕初始化函数单独跑通，用纯色刷屏验证基本数据通路，再接入 LVGL，否则一旦出问题，很难判断是渲染问题还是驱动问题。第二，SPI 时钟不要一上来就开满，先把时序和硬件稳定性压测过来再超频。第三，在 LVGL9 中如果碰到编译错误，第一时间查官方文档看 API 变更，很多旧版示例代码已经不可用。

这篇文章里没有贴出完整的代码，但是核心数据结构、回调实现方式、初始化序列组织方法都已经讲清楚了。按照这个框架去写，不管是 ST7789 还是 ILI9488，都能快速跑起来。后面如果大家需要，我可以再针对单个控制器或者 LVGL9 动画优化单独写一篇实战内容。

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