💡 本章目标：帮助您全面理解 LVGL 的配置体系，包括配置文件的作用、启用流程、路径引用、关键功能项说明及平台裁剪建议，提升嵌入式图形开发的效率与质量。

一、为什么要配置 LVGL？

---

LVGL（Light and Versatile Graphics Library）是一款轻量级、功能丰富且跨平台的嵌入式图形库，广泛应用于资源受限的嵌入式系统。出于节省资源和灵活适配不同硬件的考虑，LVGL 默认大多数功能是关闭状态。通过配置文件 lv_conf.h，您可以：

1. 精准裁剪功能模块： 只启用项目所需控件和特性，减少代码体积和内存占用。

2. 设置显示参数： 如分辨率、颜色深度，保证显示效果与硬件匹配，避免运行时错误。

3. 控制内存管理： 合理配置内存池大小，保证系统稳定运行，防止内存溢出。

4. 调试支持： 启用日志输出、断言机制，方便开发过程中的问题定位。

5. 系统集成： 结合 RTOS 或裸机系统时，配置系统时钟（Tick）同步，确保动画和刷新机制准确。

简而言之，lv_conf.h 是您 掌控 LVGL行为的核心文件，正确配置它是高效开发的前提。

二、配置启用全流程

---

很多新手开发者最大的问题是：改了配置不生效。原因并非配置语法错误，而是未正确走完配置启用流程。
配置启用三步法：

1. 复制模板配置文件（lv_conf_template.h → lv_conf.h）
2. 打开配置文件 总开关（将 #if 0 改为 #if 1）
3. 确保 lv_conf.h 被构建系统正确引用

这三个步骤是 LVGL 配置启用 的前置条件，少一步都不行！

（一）复制模板配置文件

---

LVGL 项目提供了一个配置模板文件 lv_conf_template.h，它包含了所有可配置项的默认定义，但它本身不会被自动使用。您需要复制一份并重命名为 lv_conf.h：

cp lv_conf_template.h lv_conf.h

这相当于建立了您项目专属的配置文件，方便后续定制化修改，也避免升级时模板被覆盖。

（二）打开配置文件的总开关

---

打开刚复制的 lv_conf.h，你会看到所有配置宏都包裹在如下代码块内：

#if 0 /*Set it to "1" to enable content*/

/* 大量配置宏定义 */

#endif

• #if 0 表示这一整块代码不会被编译器处理，等同于关闭。

• 只有将它改为 #if 1，配置内容才会生效。

改为：

#if 1 /*Set it to "1" to enable content*/

/* 宏定义开始生效 */

#endif

切记： 如果不执行这一步，后续你对配置的任何修改都不会产生实际效果。

（三）确保配置文件被正确引用

现在你已经成功启用了配置文件中的功能，接下来要确保 lv_conf.h 文件能够正确地被项目引用。这一步对于确保 LVGL 配置文件生效至关重要。

通常有两种常见的做法：

• 将 lv_conf.h 文件放在默认位置；
• 将其放在自定义路径下。

这两种配置方法虽然略有不同，但都相对简单。接下来，我们将一步步地解析这两种方式，帮助你根据项目结构选择最合适的配置方式。

1. 放置在默认位置

最简单、最推荐的方式是将 lv_conf.h 放在与 LVGL 源文件目录相同的位置。比如，项目目录结构如下：

project/
  ├── lvgl/
  ├── lv_conf.h   <-- 这个文件就在项目的根目录下，或者和 LVGL 文件夹并列
  └── main.c

这种方式的好处是，LVGL 内部会自动搜索该路径，无需额外配置。

2. 放置在自定义路径

如果你不想将 lv_conf.h 放在默认位置，或者希望将配置文件集中管理在另一个目录下，比如放在 config/ 文件夹内，那么需要做一些额外的配置。

• 将 lv_conf.h 放到指定目录： 假设你将文件放在 config/ 文件夹内，目录结构如下：

project/
  ├── lvgl/
  ├── config/
  │    └── lv_conf.h   <-- 这个文件放在 config 文件夹里
  └── main.c

• 配置宏 LV_CONF_INCLUDE_SIMPLE： 为了让编译器找到该配置文件，你需要在代码中添加如下语句：

#define LV_CONF_INCLUDE_SIMPLE
#include "config/lv_conf.h"

这会告诉编译器，lv_conf.h 文件不在默认位置，而是放在你指定的 config 文件夹内。

• 设置包含路径： 你还需要设置编译器的包含路径，以确保它能够找到 lv_conf.h 文件。

如果使用 Makefile，可以在 CFLAGS 中添加：

CFLAGS += -I./config

如果使用 CMake，可以通过 include_directories() 指令添加路径：

include_directories(config)

这样，编译器就会正确地找到并引用 lv_conf.h 文件。

总的来说，如果你走默认路径，最简单，开箱即用。如果你自己设了路径，那就得记得把路径和包含方式都配好，不然 LVGL 根本找不到你的配置。

三、主要配置项详解

---

以下为 LVGL 配置文件中最常用且关键的配置项，结合概念、设计意义、使用建议进行详细剖析：

（一）📐 显示分辨率

---

定义屏幕的最大逻辑分辨率，决定 LVGL 内部坐标系统范围。LVGL 在运行时，会根据此参数分配缓存和计算显示坐标，所有控件大小、布局都基于此分辨率。

#define LV_HOR_RES_MAX  480
#define LV_VER_RES_MAX  320

设定过小会导致控件显示不完整、界面裁剪异常；设定过大则占用多余内存，增加渲染负担；必须严格与硬件屏幕分辨率匹配。

（二）🎨 颜色深度

---

定义像素的位深，影响颜色表现和内存消耗。

#define LV_COLOR_DEPTH  16

常用选项及场景：

• 1-bit：单色，适合极限节省资源的场景；

• 8-bit：带调色板，适合简单色彩需求；

• 16-bit (RGB565)：嵌入式中最普遍，兼顾色彩和性能；

• 32-bit (ARGB8888)：高端平台或 PC 模拟使用，支持透明度。

还可以控制 Alpha 通道，启用屏幕透明色，支持特殊叠加效果：

#define LV_COLOR_SCREEN_TRANSP    1

（三）🧠 内存池设置

---

LVGL 维护一个 私有内存池，用于控件、动画、图形缓存等动态分配。此宏定义池大小（字节数）。

#define LV_MEM_SIZE  (32 * 1024)

避免直接使用系统动态内存，保障内存分配确定性和碎片最小化；确保对内存使用有明确控制。

如果你希望使用外部动态内存管理器（如 malloc），可改用：

#define LV_MEM_CUSTOM     1
#define LV_MEM_CUSTOM_INCLUDE "stdlib.h"
#define LV_MEM_CUSTOM_ALLOC   malloc
#define LV_MEM_CUSTOM_FREE    free

建议： 根据项目控件数量、动画复杂度调整大小，内存不足会导致控件创建失败或显示异常。

（四）🧪 日志输出与断言

---

调试时启用日志输出，可帮助定位错误与性能瓶颈。

#define LV_USE_LOG        1
#define LV_LOG_LEVEL      LV_LOG_LEVEL_WARN
#define LV_LOG_PRINTF     1

日志级别可设为：

• LV_LOG_LEVEL_TRACE：最详细，开发初期建议使用；

• LV_LOG_LEVEL_INFO：一般信息；

• LV_LOG_LEVEL_WARN：警告信息；

• LV_LOG_LEVEL_ERROR：仅错误信息；

• LV_LOG_LEVEL_NONE：关闭日志。

推荐开发调试期间开启，发布版本关闭。

断言配置：

#define LV_USE_ASSERT_NULL 1
#define LV_USE_ASSERT_MEM  1

开启后，程序会在异常指针或内存问题时触发断言，方便调试。

建议： 开发期间开启，发布版本关闭以节省资源。

（五）🧩 控件模块开关

---

LVGL 的控件非常丰富，默认全部关闭。你必须手动开启需要的控件（LV_USE_*），避免不必要的代码和内存开销。

#define LV_USE_LABEL      1
#define LV_USE_BTN        1
#define LV_USE_IMG        1
#define LV_USE_SLIDER     1
#define LV_USE_ARC        0

建议根据项目需求启用所需模块，避免资源浪费。

（六）⏱️ Tick 时间管理

---

LVGL 依赖定时的 Tick 触发刷新和动画更新。默认 Tick 使用内部计时器。在使用 RTOS（如 FreeRTOS）时，推荐使用系统 Tick，确保时间同步与效率。

#define LV_TICK_CUSTOM              1
#define LV_TICK_CUSTOM_INCLUDE      "freertos.h"
#define LV_TICK_CUSTOM_SYS_TIME_EXPR (xTaskGetTickCount() * portTICK_PERIOD_MS)

这是确保动画与刷新同步的关键配置。

四、平台配置参考

---

针对不同硬件平台，推荐如下配置以平衡性能和资源：

（一）STM32（如 F103 + ILI9341）

#define LV_HOR_RES_MAX  320
#define LV_VER_RES_MAX  240
#define LV_COLOR_DEPTH  16
#define LV_MEM_SIZE     (16 * 1024)
#define LV_USE_LABEL    1
#define LV_USE_BTN      1
#define LV_USE_IMG      1
#define LV_USE_LOG      0

适合中小型嵌入式屏幕，资源有限，关闭日志以节省内存。

（二）PC 模拟平台

#define LV_HOR_RES_MAX  800
#define LV_VER_RES_MAX  480
#define LV_COLOR_DEPTH  32
#define LV_MEM_SIZE     (64 * 1024)
#define LV_USE_LOG      1
#define LV_LOG_PRINTF   1

PC 资源（SDL、Win32）充足，开启日志方便调试，使用高色深提升显示效果。

五、其他推荐配置项

---

宏名称	作用	建议
LV_FONT_DEFAULT	默认字体	使用 &lv_font_montserrat_14
LV_USE_THEME_DEFAULT	是否启用默认主题	推荐开启
LV_USE_GPU	是否启用 GPU 加速支持	依硬件平台决定
LV_USE_PERF_MONITOR	性能监视窗口	开发调试期间开启
LV_DISP_DEF_REFR_PERIOD	显示刷新周期（毫秒）	默认 30ms，可根据需求调整
LV_USE_DRAW_MASKS	启用绘图遮罩	需要高级 UI 效果时开启

六、总结与实践建议

---

1. lv_conf.h 是 LVGL 的中枢神经： 它集中管理了图形库的核心配置，合理而精准的设置直接关系到项目的性能表现和运行稳定性，是确保系统高效运行的基础。
2. 严格遵循配置启用流程： 包括复制模板文件、打开配置总开关、正确配置文件路径以及编辑具体功能选项。这四个步骤缺一不可，确保所有配置生效且被编译器正确识别。
3. 结合项目实际资源与需求进行裁剪： 精准启用所需控件和功能模块，杜绝冗余配置，避免浪费宝贵的内存和计算资源，从而提升系统响应速度和稳定性。
4. 分阶段合理使用日志和断言机制： 在开发调试阶段，开启日志输出和断言检查，有助于及时发现问题和定位缺陷；而在产品发布阶段，为节省资源，应关闭这些调试功能。
5. 配置与构建系统密不可分： 配置项的生效依赖于构建脚本对路径和宏定义的正确管理。务必确保构建环境与配置文件保持同步，以避免配置失效或编译异常。

通过本章的深入讲解，您已系统掌握了 LVGL 配置体系的核心要点，理解了配置文件的作用、启用流程和路径管理方法。这为您灵活裁剪功能模块、优化资源使用奠定了坚实基础。

然而，在嵌入式项目中，配置只是成功的关键一步，合理选择和应用构建方案同样不可忽视，它直接影响开发效率和系统集成的质量。

下一章将带您全面了解 LVGL 支持的四种主流构建方式——Make、CMake、SCons 和 Kconfig。我们将深入比较它们的特点和适用场景，帮助您结合项目实际需求，选择最优构建方案，实现 LVGL 的高效集成与灵活应用。

📘 请继续阅读下一篇：《[ LVGL ] 构建方式》。