企业官网建设流程全解析

简介：《LVGL开发指南（中文V1.3）》是正点原子面向STM32开发板编写的嵌入式图形库学习文档，适合正在做MCU界面开发、需要把LVGL落地到实际项目的初学者和中级工程师，重点解决移植流程不清晰、控件使用与系统集成缺少参考的问题。整包仅含1个PDF文件，约9.54MB，单文件结构便于按章节检索和离线阅读。目前已有766人学习下载。内容从初识LVGL、移植要求与源码获取讲起，依次展开无操作系统移植、FreeRTOS环境移植、PC模拟器使用及LVGL初始化流程，并延伸到控件创建、动画交互和性能优化等应用开发主题，可配合正点原子STM32板卡对照实践，帮助读者建立从环境搭建、显示验证到界面功能实现的完整认知。

1. 从一块 320×240 的屏说起：这份 V1.3 中文指南能省掉哪几周试错

手上有一块带 LCD 的 STM32 板子，跑通了点屏例程，接下来想把界面做出来——很多人就卡在这一步。真正费时间的不是写lv_label_set_text，而是移植：源码目录往哪放、lv_conf.h里哪几个宏必须动、flush回调怎么写、屏上花了一块到底是色深、字节序还是 DMA 打架。这份 V1.3 版中文开发指南（2023 年 1 月更新，比上一版修了例程功能、纠正了部分描述）就是冲着这些具体问题写的，从无操作系统移植、FreeRTOS 移植一路讲到对象模型、样式、动画、文件系统和字库，部件篇又把 arc、bar、btn 这些常用控件逐个拆开。适合已经能把屏点亮、想把 GUI 从「看个亮」做到「能交付」的嵌入式开发者，也适合刚接手一个现成 LVGL 工程、需要快速摸清配置项的人。GUI 调试的坑最耗时间，有份对口的中文资料，能少翻不少英文 issue。

2. 移植前先算三笔账：源码目录、绘制缓冲区与 lv_conf.h

2.1 源码目录怎么摆：其实只需要 lvgl 根目录下的四样东西

从官方仓库拉下来的lvgl目录看起来很唬人，几百个文件，但真正必须参与编译的只有src和lvgl.h，lv_conf_template.h要改名后搬到工程里，examples和demos属于验证阶段的拐杖，量产时该删就删。教程配套的工程模板走的就是「整个目录原样挂进工程」这条稳妥路线，好处是升级方便，坏处是编译时间长、include 路径容易漏。我的习惯是先把整个目录搬进去跑通，再回头做裁剪，别一上来就手工挑文件，那样出了问题根本分不清是裁错了还是配错了。

# 移植阶段推荐的目录形态，lvgl 整个目录挂在工程根下 Project/ ├── Core/ # 芯片厂商生成的启动、时钟、外设初始化 ├── Drivers/ # 片内外设驱动库 ├── LVGL/ # 从官方仓库拉下来的 lvgl 目录，原样搬运 │ ├── src/ │ │ ├── core/ # lv_obj、lv_disp、lv_indev、lv_event 这些地基 │ │ ├── draw/ # 软件渲染、颜色混合、圆弧与线段绘制 │ │ ├── font/ # 内置字模与字库解析 │ │ ├── hal/ # 时基、文件系统对接的钩子 │ │ ├── misc/ # 数学、内存池、链表、日志封装 │ │ ├── widgets/ # btn/label/bar/arc/chart 这些控件 │ │ └── extra/ # 布局、主题、第三方解码库 │ ├── examples/ # 验证阶段用，量产可删 │ ├── demos/ # 综合演示，很吃 flash │ ├── lvgl.h # 唯一的总入口头文件 │ └── lv_conf_template.h# 模板，改名 lv_conf.h 后放到上一级目录 └── User/ ├── lv_conf.h # 最终生效的配置文件 └── main.c

这段目录树的关键信息在最后两行：lv_conf.h不是放在lvgl/目录里面，而是放在它的上一级。原因是lvgl.h里有一段条件包含逻辑——定义了LV_CONF_INCLUDE_SIMPLE就按"lv_conf.h"找，不定义就按"../../lv_conf.h"找。新手最常见的翻车是「明明改了配置却一点反应都没有」，八成就是位置放错、或者模板开头的#if 0没改成#if 1，编译器压根没把那段配置编进去。裁剪widgets时也要注意，lv_conf.h里的LV_USE_BTN、LV_USE_ARC这类开关关掉之后，对应的.c文件整体被预处理掉，省的是 flash 不是编译时间，所以别指望关了就能快多少。

提示：先把整个lvgl目录跑通再裁剪，顺序反了会同时面对「配置问题」和「文件缺失问题」两类错误，排查成本翻倍。

2.2 绘制缓冲区：一行缓冲、十行缓冲还是全屏双缓冲

LVGL 不是直接往显存里画，它先在 RAM 里准备一小块「绘制缓冲区」，画完一块再通过你的flush回调搬到屏上。这块缓冲区多大，直接决定 RAM 开销和刷新体验。算一笔账：320×240 的屏、RGB565 每像素 2 字节，全屏单缓冲需要 153600 字节，绝大多数片内 SRAM 根本放不下；而 20 行缓冲只要320 × 20 × 2 = 12800字节，片内 RAM 完全吃得下，代价是刷一次全屏要分 12 次搬运。教程里把「绘制缓冲区」单列一节讲，就是因为这个参数没有标准答案，只有权衡。

双缓冲的意义不在于「画得更快」，而在于 DMA 搬运上一块的同时 CPU 可以继续画下一块，把搬运时间藏起来。用双缓冲时lv_disp_drv_t里的full_refresh和缓冲模式要配对设置，否则 LVGL 会按单缓冲的逻辑调度，双缓冲白配。还有一个容易被忽略的点：缓冲区必须按LV_ATTRIBUTE_MEM_ALIGN对齐，用 DMA 时如果源地址没对齐到 4 字节，搬运出来的像素会整体错位半个像素，表现出来就是画面「斜着花」。

2.3 lv_conf.h：先动这五个宏，别一上来全改

配置文件几百行，第一次打开很容易陷入「每个都想调」的状态。实用的做法是先只改和硬件强相关的几个，让画面能出第一帧，剩下的等有具体需求再回来。下面这段是移植阶段真正会动到的部分，其余保持默认。

/* lv_conf.h —— 移植阶段先动这几个宏，其余保持模板默认值 */ #define LV_COLOR_DEPTH 16 /* 必须和屏的接口一致：RGB565 屏写 16，RGB888 写 32 */ #define LV_COLOR_16_SWAP 0 /* 屏是 RGB565 但红蓝反了、画面偏紫，就改成 1 */ #define LV_MEM_CUSTOM 0 /* 0=用 LVGL 自带的静态内存池；1=接管 malloc/free */ #define LV_MEM_SIZE (48U * 1024U) /* 仅当 LV_MEM_CUSTOM=0 时有效，按控件数量给 */ #define LV_DISP_DEF_REFR_PERIOD 30 /* 刷新周期 ms，30ms≈33Hz，不要小于一帧的实际绘制耗时 */ #define LV_INDEV_DEF_READ_PERIOD 30 /* 输入扫描周期 ms，触摸响应慢可以降到 20 */ #define LV_USE_LOG 1 #define LV_LOG_LEVEL LV_LOG_LEVEL_WARN /* 先 WARN，稳定后关掉，日志本身也吃时间 */

LV_COLOR_DEPTH和LV_COLOR_16_SWAP是最容易搞错的一对。色深写错，屏上会出现大块色带或者干脆全黑；色深对但字节序反了，表现是红色变蓝、白色正常、肤色发青，这种「只错颜色不错形状」的现象基本可以锁定是字节序问题。LV_MEM_SIZE只在LV_MEM_CUSTOM = 0时生效，一旦改成 1 交给系统的堆，这个值填多少都没意义，这个坑不少人踩过——内存明明调大了还是分配失败，因为根本没走这条路。LV_DISP_DEF_REFR_PERIOD不要为了追求流畅硬压到 10ms，如果一帧的实际绘制加搬运要 25ms，设成 10ms 只会让lv_timer_handler每次都超时返回，CPU 占用飙上去而画面一点没变快。

注意：改完lv_conf.h一定要全量重编，很多 IDE 的增量编译对头文件依赖跟踪不完整，改宏不生效的现象有相当一部分是编译缓存造成的。

3. 无操作系统移植：从添加文件到点亮第一帧

3.1 把文件搬进工程：include 路径与配置文件的三个开关

文件搬完之后，工程设置里至少要加三条 include 路径：LVGL（为了找到lvgl.h）、LVGL/src（内部头文件互相引用）、以及lv_conf.h所在的目录。教程配套工程里这些路径是配好的，自己新建工程时漏掉任何一条，报错信息都不会直白告诉你「路径没加」，而是lvgl.h: No such file or directory或者一堆undefined identifier lv_obj_t，看着像库坏了，其实是找不到头文件。

配置文件这边有三个开关决定它能不能被找到，按优先级从高到低是：LV_CONF_PATH直接给绝对或相对路径、LV_CONF_INCLUDE_SIMPLE按简单文件名找、都没有就走默认的../../lv_conf.h。工程结构规整的话，我一般打开LV_CONF_INCLUDE_SIMPLE并把lv_conf.h放在User/下，然后把User加进 include 路径，这样目录怎么挪都不会断。模板文件开头的那个#if 0是必须改的，很多人复制完就忘了。

/* lv_conf.h 文件开头，模板默认是 #if 0，不改这一行后面所有配置全部失效 */ #if 1 /* 原来是 0，改成 1 才会参与编译 */ #ifndef LV_CONF_H #define LV_CONF_H #include <stdint.h> /* 从这里开始才是真正的配置项 */ #define LV_COLOR_DEPTH 16 /* ... */ #endif /* LV_CONF_H */ #endif /* 结尾对应的就是开头那个 #if */

这段代码没有技术含量，但它是「配置不生效」类问题的第一检查点。判断方法很简单：故意把LV_COLOR_DEPTH改成一个明显错误的值（比如 8），重新编译，如果画面没有任何变化，说明这个lv_conf.h根本没被包含进来，别再往下调参数了，先解决路径和包含问题。

3.2 显示驱动：flush 回调是整个移植中最重要的环节

LVGL 和硬件之间只有两个约定：我给你一块矩形区域的像素，你把它显示到屏上；显示完了告诉我一声。前者是flush_cb，后者是lv_disp_flush_ready。这个回调写不对，后面所有界面代码都是白搭。教程用一整节讲「注册显示驱动」，核心就是这个函数。

/* 显示刷新回调：LVGL 画好一块矩形，这里负责搬到 LCD 上 */ static void disp_flush(lv_disp_drv_t *drv, const lv_area_t *area, lv_color_t *px_map) { /* 1. 算矩形宽高，area 是闭区间，别忘了 +1 */ uint32_t w = (area->x2 - area->x1 + 1); uint32_t h = (area->y2 - area->y1 + 1); /* 2. 设置 LCD 的显示窗口，再往里灌像素，这两步各家屏驱动名字不同 */ lcd_set_window(area->x1, area->y1, w, h); lcd_write_pixels((uint16_t *)px_map, w * h); /* 3. 必须调用，否则 LVGL 会一直等这一块刷完，整个界面停住 */ lv_disp_flush_ready(drv); }

第 1 步的+1是我见过的最高频错误，漏掉之后画面整体会缺最后一行和最后一列，界面看起来「被裁掉了一点」，而且因为每块都少一行，滑动列表时会看到一条细缝缓慢移动。第 3 步的lv_disp_flush_ready如果用的是阻塞式写屏（CPU 一条条往并口或 SPI 灌），放在函数末尾没问题；一旦改成 DMA 异步搬运，这个调用就必须挪到 DMA 传输完成中断里，在回调函数末尾调会立刻引发下一块覆盖当前正在搬的缓冲区，画面碎成雪花。这个改法很反直觉——代码看起来「顺序执行」，实际是并发的，翻车现场往往只在滑动时才出现。

注册流程本身不复杂，填一个lv_disp_drv_t结构体，把hor_res、ver_res、flush_cb、draw_buf填上，然后lv_disp_drv_register。缓冲区用lv_disp_draw_buf_init初始化，单缓冲时第二个参数传NULL。这一步之后调一次lv_timer_handler，屏幕就该出现 LVGL 的默认背景色了，能出这个颜色就说明链路是通的。

3.3 时基与主循环：lv_tick_inc 和 lv_timer_handler 的分工

LVGL 需要知道「现在过了多少毫秒」，这靠lv_tick_inc喂进去；它还需要有人定期驱动内部定时器、动画和刷新，这靠lv_timer_handler。两者分工明确，混用会出各种奇怪的时间问题，比如动画速度忽快忽慢、控件超时判定的时间对不上。

/* 1ms 一次的 SysTick 中断里喂时基，只加不减，LVGL 内部自己处理回绕 */ void SysTick_Handler(void) { lv_tick_inc(1); } /* 主循环：不要在这里加固定延时，让 handler 自己算下一次该等多久 */ int main(void) { /* ... 时钟、外设、LCD 初始化 ... */ lv_init(); lv_port_disp_init(); /* 内部完成 draw_buf 与 disp_drv 的注册 */ lv_port_indev_init(); /* 触摸或按键 */ while (1) { lv_timer_handler(); /* 内部会按需刷新，刷完就返回 */ app_work(); /* 自己的业务逻辑，单次执行控制在 5ms 内 */ } }

lv_tick_inc(1)放在 1ms 中断里，前提是中断真的每 1ms 进一次；如果系统时钟配错，时基就是错的，动画会明显偏快或偏慢，这种问题很难靠看代码发现，只能用秒表对一下动画设置的时长。主循环里的app_work()单次执行时间要控制住，一旦超过几毫秒，lv_timer_handler的调用间隔就被拉长，表现出来是界面「一顿一顿」，而不是报错。

提示：调试阶段可以在主循环里翻转一个空闲 GPIO，用示波器看lv_timer_handler的实际调用周期，比看代码猜快得多。

3.4 触摸与按键：indev 驱动的注册与去抖

输入设备的注册方式和显示几乎对称，填lv_indev_drv_t，给一个read_cb，然后lv_indev_drv_register。区别在于read_cb是被周期性轮询调用的，不是事件驱动，所以去抖、滤波这些活要么在底层驱动做，要么在这个回调里做。

/* 触摸读取回调，LVGL 按 LV_INDEV_DEF_READ_PERIOD 周期调用 */ static void touch_read(lv_indev_drv_t *drv, lv_indev_data_t *data) { static lv_coord_t last_x = 0, last_y = 0; lv_coord_t x, y; if (tp_is_pressed(&x, &y)) { /* 原始坐标要先做方向和范围换算，否则点左边响应右边 */ last_x = map_x(x); last_y = map_y(y); >static SemaphoreHandle_t lv_mutex; /* 初始化时创建，别用递归锁，容易掩盖设计问题 */ void ui_lock_init(void) { lv_mutex = xSemaphoreCreateMutex(); } /* 业务任务改界面统一走这个封装，不要到处裸调 lv_xxx */ bool ui_set_bar_value(lv_obj_t *bar, int32_t v) { if (xSemaphoreTake(lv_mutex, pdMS_TO_TICKS(50)) != pdTRUE) { return false; /* 拿不到锁就丢弃这次刷新，比死等更安全 */ } lv_bar_set_value(bar, v, LV_ANIM_OFF); xSemaphoreGive(lv_mutex); return true; } /* GUI 任务里同样要加锁，否则和上面的业务任务照样打架 */ static void gui_task(void *arg) { while (1) { if (xSemaphoreTake(lv_mutex, portMAX_DELAY) == pdTRUE) { lv_timer_handler(); xSemaphoreGive(lv_mutex); } vTaskDelay(pdMS_TO_TICKS(5)); } }

参数上要注意超时时间：业务侧给 50ms 是个经验值，够拿到锁又不至于把业务任务卡死；GUI 侧用portMAX_DELAY，因为它拿不到锁就没法工作，等下去是合理的。另一个容易漏的点是lv_timer_handler持有锁的整段时间里，业务任务全部在等，所以 handler 单次执行时间越长，系统的实时性越差，这也是为什么前面强调别把刷新周期压得太狠。

4.3 时基与内存：把 SysTick 让给 OS，把堆交给 LVGL

裸机下自己在 SysTick 里lv_tick_inc(1)，上了 FreeRTOS 之后 SysTick 已经被系统占用，再往里塞代码要么改中断向量，要么和系统的 tick 计数打架。正确的做法是用系统的 tick 钩子，或者干脆让 LVGL 直接读系统的计数器。

/* 方案一：打开 FreeRTOS 的 tick 钩子，在里面喂时基 */ /* FreeRTOSConfig.h 里需要 #define configUSE_TICK_HOOK 1 */ void vApplicationTickHook(void) { lv_tick_inc(1); /* 前提是 configTICK_RATE_HZ = 1000，否则这里不是 1ms */ } /* 方案二：不写钩子，直接在 lv_conf.h 里把时基指过去，代码更少 */ #define LV_TICK_CUSTOM 1 #define LV_TICK_CUSTOM_INCLUDE "FreeRTOS.h" #define LV_TICK_CUSTOM_SYS_TIME_EXPR (xTaskGetTickCount() * portTICK_PERIOD_MS)

方案一的关键前提是 tick 频率必须是 1000Hz，如果工程里配的是 100Hz，一次 tick 是 10ms，还按 1 喂进去，所有动画会快十倍。这种错误不会报错，只会让你怀疑「LVGL 的动画是不是有问题」。方案二更省事，但每次取时间要做一次乘法，在 1ms 级的定时器密集场景下有一点点开销，一般可以忽略。

内存这块，带 OS 之后LV_MEM_CUSTOM通常改成 1，让 LVGL 直接用系统的malloc/free，好处是内存池不再是一块固定大小的静态数组，坏处是堆碎片。如果界面控件数量固定、创建删除不频繁，我反而倾向保持LV_MEM_CUSTOM = 0，给一个够用的静态池，碎片问题从根上就没有了。

5. 排查清单：移植阶段最容易出问题的五处

5.1 显示异常：花屏、偏色与图像斜着撕

现象一：上电后屏幕大块色带、颜色明显不对，或者整个画面糊成一片。原因：LV_COLOR_DEPTH和实际接口位宽不匹配，或者LV_COLOR_16_SWAP的字节序设反。RGB565 的屏如果按 32 位色深去配，LVGL 按每像素 4 字节算地址，搬过去就全乱了。解决：先只显示一个纯色矩形，红、绿、蓝各来一次，看哪个通道错位。红色显示成蓝色基本就是字节序，把LV_COLOR_16_SWAP取反再试；如果三个颜色全错，回到色深。

现象二：静态界面正常，一滑动列表就出现横向撕裂，或者画面斜着错位。原因：绘制缓冲区正在被 DMA 搬运，CPU 已经往里写下一帧了。异步 DMA 场景下在flush_cb末尾调lv_disp_flush_ready就会这样。解决：把lv_disp_flush_ready挪到 DMA 传输完成中断里；或者改用双缓冲，让 CPU 和 DMA 各用各的缓冲。同时检查缓冲区地址是否 4 字节对齐。

5.2 运行异常：跑几秒就死机、界面点不动

现象三：上电跑几秒到几十秒后 HardFault，复现位置随机。原因：GUI 任务的栈溢出。LVGL 绘制递归深度和控件层级相关，嵌套容器一多，局部变量吃得很快，1KB 栈撑不住。解决：把 GUI 任务栈临时翻倍验证，如果问题消失就是栈的问题。用调试器看栈水位，按实际峰值的 1.5 倍定值。顺带检查LV_MEM_SIZE是否够用，内存分配失败时 LVGL 会返回NULL，后面继续用这个空指针同样会崩。

现象四：界面完全不刷新，或者点了没反应，但程序没死。原因：lv_timer_handler根本没被调到，或者某处阻塞把它卡住了。常见于把lv_timer_handler放在一个低优先级任务里，而这个任务被高优先级任务长期饿死；也可能是在某个回调里写了死循环等待。解决：在 handler 前后各翻转一个 GPIO，用示波器看实际调用周期。如果周期远大于设定值，往上查是哪个任务占着 CPU 不放。

5.3 输入与字体：坐标偏移、中文变方块

现象五：触摸位置整体偏移，或者中文标签显示成一串方块、问号。原因：坐标偏移多半是没有做屏幕方向和分辨率换算，横屏工程用了竖屏原始坐标；方块则是字库没开 UTF-8 编码，或者自定义字库里根本没收这些汉字。LVGL 内置字库只覆盖 ASCII 和少量符号，中文必须自己生成。解决：先把触摸原始坐标打印出来，在屏幕四角各点一次，看数值范围是否和分辨率一致，不一致就在read_cb里做线性映射。中文问题先确认源文件保存为 UTF-8，再把自定义字库用LV_FONT_DECLARE引入并设到控件的text_font样式上，两者缺一不可。

6. 从例程到产品：字库按需裁剪与刷新率的实测方法

界面能跑起来之后，接下来两个问题几乎一定会碰到：flash 不够放中文字库，以及「到底流不流畅」全靠感觉。这两件事都有量化的做法。

字库方面，全量汉字在 16 号、4bpp 下动辄几百 KB 到 MB 级，小容量 flash 根本放不下。可行的做法是用官方字体转换工具按项目实际用到的字符生成，把所有界面文案里的汉字去重后拼成一个字符串传进去，通常只有几十到一两百个字，生成的文件能压到几 KB。

# 用官方字体转换工具生成只含项目用字的字库 # --bpp 抗锯齿等级 1/2/4/8，越高越吃 flash，小屏 4 够用 # --symbols 直接列出实际用到的汉字，比按 Unicode 区间裁省得多 # --range 0x20-0x7F 保留 ASCII，数字和英文不用另外做字库 lv_font_conv --font your-font.otf \ --size 16 --bpp 4 --format lvgl \ --symbols "开始停止运行参数设置返回主页温度湿度电压电流" \ --range 0x20-0x7F \ -o my_font_16.c

生成后在用到的地方声明并挂到样式上，注意lv_obj_set_style_text_font的第三个参数是选择器，传 0 表示默认状态，如果传了LV_STATE_DISABLED之类的值，只在那个状态下生效，正常状态反而看不到效果。

LV_FONT_DECLARE(my_font_16); /* 声明，放头文件里更规范 */ void ui_init(void) { lv_obj_t *label = lv_label_create(lv_scr_act()); lv_obj_set_style_text_font(label, &my_font_16, 0); /* 0 = 默认状态 */ lv_label_set_text(label, "温度 25.3"); }

刷新率方面，别用眼睛判断。在flush_cb里按刷新的像素面积累加，每秒统计一次，换算成「等效全屏帧数」，这个数字比任何主观感受都可靠。

static volatile uint32_t s_px_total; static void disp_flush(lv_disp_drv_t *drv, const lv_area_t *area, lv_color_t *px_map) { uint32_t w = lv_area_get_width(area); uint32_t h = lv_area_get_height(area); lcd_set_window(area->x1, area->y1, w, h); lcd_write_pixels((uint16_t *)px_map, w * h); s_px_total += w * h; /* 累计像素数，刷一次全屏等于 320*240 */ lv_disp_flush_ready(drv); } /* 每秒钟调一次：像素数 / 屏幕总像素 = 等效全屏帧数 */ void perf_report(void) { uint32_t px = s_px_total; uint32_t x100; s_px_total = 0; x100 = px * 100UL / (320UL * 240UL); printf("eq-fps = %lu.%02lu\r\n", x100 / 100, x100 % 100); }

之所以要按面积加权，是因为 LVGL 大部分时间只在刷变化的小区域，直接数flush_cb的调用次数会得到一个虚高得离谱的数字。这个指标测出来低于 20 时，优先去查缓冲区行数够不够、flush里有没有阻塞式延时；高于 30 还觉得卡，问题多半在业务任务抢 CPU，而不在绘制本身。

血泪经验是：我曾经在一个项目上花了三天优化绘制，最后发现是某个业务任务里有一句printf阻塞了串口，把整个 GUI 任务拖慢。从那以后我每次调 GUI 性能，都强制先把这个等效帧率打出来跑一遍，再决定往哪个方向优化，免得又对着错误的目标使劲。希望帮到你。

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