SQLite通常以amalgamation形式发布，也就是把数十万行实现合并进一个sqlite3.c文件。默认情况下，这个文件会编译出功能完整的数据库引擎。但很多业务场景并不需要全部功能，比如嵌入式设备可能只需要基本的SQL查询与事务，不希望携带JSON1、FTS5、RTREE等扩展。好消息是，SQLite的构建系统并没有把这些模块真正分离成多个库，而是通过预处理宏在编译时决定哪些代码保留、哪些代码彻底不参与编译。这就是编译选项定制的核心。
要让裁剪生效，宏必须在编译sqlite3.c之前定义。可以用编译器参数-D传入，也可以统一写入构建脚本。如果只修改某个头文件里的默认值，维护成本会很高，而且容易在升级SQLite版本时丢失。因此推荐使用集中的配置头文件或构建变量。
一、编译选项的两大类型：OMIT移除与ENABLE开启
SQLite的编译选项主要分为两类。SQLITE_OMIT_* 系列用于从构建中移除特定功能，例如 SQLITE_OMIT_FLOATING_POINT 会去掉浮点运算支持，SQLITE_OMIT_LOAD_EXTENSION 禁止运行时加载扩展库，SQLITE_OMIT_AUTOINCREMENT 移除自动增长关键字。移除功能后，相关代码不会出现在目标文件中，既能减小体积，也能降低潜在攻击面。
另一类是 SQLITE_ENABLE_* 系列，用来开启默认未启用的可选能力。例如 SQLITE_ENABLE_FTS5 打开全文检索，SQLITE_ENABLE_RTREE 打开空间索引，SQLITE_ENABLE_MATH_FUNCTIONS 启用数学函数。需要注意，ENABLE 不一定增加很多代码，但一旦开启，就应当测试相应功能是否与业务兼容。
下面是一个在Linux下使用GCC编译精简SQLite静态库的命令，注意所有配置都在编译命令行上完成，不需要修改源码：
gcc -Os -ffunction-sections -fdata-sections \ -DSQLITE_OMIT_LOAD_EXTENSION \ -DSQLITE_OMIT_DEPRECATED \ -DSQLITE_OMIT_AUTOINCREMENT \ -DSQLITE_THREADSAFE=0 \ -c sqlite3.c -o sqlite3.o ar rcs libsqlite3.a sqlite3.o
这段命令同时启用了函数级分节，方便链接器使用 --gc-sections 进一步丢弃未引用代码。实际效果取决于工具链，但在GNU工具链下通常能明显压缩体积。
二、常用选项组合与体积性能权衡
裁剪并非一股脑把所有OMIT选项都加上。盲目堆叠宏可能导致SQLite内部依赖不满足，出现编译错误。比如移除了 SQLITE_OMIT_FLOATING_POINT 后，如果业务表的字段类型还包含 REAL，运行时行为会发生变化。再比如禁用 SQLITE_OMIT_LOAD_EXTENSION 能减少动态库加载风险，但也会让后续无法使用自定义函数扩展，若上层代码依赖扩展能力，就会直接失败。
常见的精简组合可以优先考虑这几个选项：SQLITE_OMIT_DEPRECATED、SQLITE_OMIT_LOAD_EXTENSION、SQLITE_OMIT_AUTOINCREMENT、SQLITE_OMIT_UTF16。它们对多数嵌入式存储场景影响较小，体积收益明显。若确实不需要全文检索和JSON，可以再添加 SQLITE_OMIT_JSON、SQLITE_OMIT_FTS3、SQLITE_OMIT_FTS5 等。下面的表格列出部分选项及影响：
| 编译选项 | 作用 | 典型影响 |
|---|---|---|
| SQLITE_OMIT_LOAD_EXTENSION | 禁止动态加载扩展 | 减小体积，增强安全 |
| SQLITE_OMIT_DEPRECATED | 移除废弃接口 | 避免误用旧API |
| SQLITE_OMIT_AUTOINCREMENT | 去掉AUTOINCREMENT关键字 | 减少少量代码 |
| SQLITE_ENABLE_FTS5 | 启用全文检索模块 | 增加功能与体积 |
| SQLITE_ENABLE_MATH_FUNCTIONS | 启用数学函数 | 增加扩展函数集 |
需要指出，单纯依靠OMIT选项的裁剪空间有时有限，因为SQLite核心仍会保留内存管理、VDBE、B树等基础组件。真正把体积做到极致的项目，通常还会配合编译告警、链接器垃圾回收和自定义VFS。对于资源极度紧张的平台，可以维护一个最小VFS实现，仅保留需要的存储操作，但复杂度较高，不建议一开始就尝试。
如果目标平台是桌面或移动端，体积并不那么敏感，反而可以通过ENABLE选项获得更多能力。例如 SQLITE_ENABLE_COLUMN_METADATA 允许获取列的元数据，SQLITE_ENABLE_DBSTAT_VTAB 提供数据库统计虚拟表。增加这些功能前最好评估二进制增量和启动开销。
三、完整的自定义构建流程与验证方法
自定义构建不只是改几个宏，建议把配置放在构建系统中统一管理。以CMake为例，可以先下载SQLite官方amalgamation源文件，然后在CMakeLists.txt中通过 target_compile_definitions 传递宏：
cmake_minimum_required(VERSION 3.16)
project(sqlite_custom)
add_library(sqlite3 STATIC sqlite3.c)
target_include_directories(sqlite3 PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
target_compile_definitions(sqlite3 PRIVATE
SQLITE_THREADSAFE=0
SQLITE_OMIT_LOAD_EXTENSION
SQLITE_OMIT_DEPRECATED
SQLITE_OMIT_AUTOINCREMENT
SQLITE_OMIT_UTF16
)
set_target_properties(sqlite3 PROPERTIES C_STANDARD 99)
这段配置生成一个静态库，对外暴露sqlite3.h，内部编译时使用精简选项。如果项目后续需要打开其他能力，只需在 target_compile_definitions 中增加，不需要改动SQLite源码。
编译完成后必须验证实际启用的编译选项。SQLite提供了 PRAGMA compile_options; 语句，可以返回当前库编译时使用的主要宏。可以写一个小程序调用 sqlite3_exec 执行该语句并打印结果：
#include <stdio.h>
#include <sqlite3.h>
static int dump_option(void *ctx, int cols, char **vals, char **names) {
(void)ctx; (void)cols; (void)names;
printf("%s\n", vals[0]);
return 0;
}
int main(void) {
sqlite3 *db = NULL;
if (sqlite3_open(":memory:", &db) != SQLITE_OK) {
return 1;
}
sqlite3_exec(db, "PRAGMA compile_options;", dump_option, NULL, NULL);
sqlite3_close(db);
return 0;
}
运行后观察输出中是否包含预期的 SQLITE_OMIT_LOAD_EXTENSION 或 SQLITE_THREADSAFE=0。如果缺少某项，需要回到构建系统检查宏是否真正传递给编译器。某些配置工具会忽略跨目录的头文件定义，因此在编译命令后追加 -v 查看实际参数也是有效的排查手段。
此外，要针对裁剪后的库跑一遍业务相关SQL语句，尤其关注被移除功能相关的类型、关键字。例如移除 SQLITE_OMIT_AUTOINCREMENT 后，建表语句中的 AUTOINCREMENT 会被忽略或报错，需要提前调整表结构设计。
四、避坑：线程安全、ABI一致性与升级维护
自定义构建最容易忽略的是线程模型。如果将 SQLITE_THREADSAFE 设为0，SQLite会省略互斥和线程安全检查，体积更小、速度更快，但同一个数据库连接同时被多个线程使用就不再安全。此时应该由上层保证串行访问，或者每个线程创建独立连接。若设为1或2，还需要考虑链接时是否同时链接了系统自带的线程库。
另一个常见问题是动态库与可执行程序之间编译选项不一致。比如程序A使用系统自带SQLite动态库，而插件B静态链接了自己裁剪过的SQLite，两者若同时出现在同一进程，会出现重复符号或行为不一致。因此在一个工程中应尽量统一SQLite构建方式，要么全部动态链接，要么全部静态链接。
升级SQLite版本时，不要假设上一版自定义选项全部兼容。某些 SQLITE_OMIT_* 宏可能被合并、改名或在内部依赖关系上发生变化。建议每次升级都在构建脚本中重新核对文档，并运行测试集。官方提供的编译选项清单会随版本更新，可以将其纳入持续集成检查，一旦出现未知宏就告警。
最终，SQLite编译选项与自定义构建的目标不是追求最小体积本身，而是让依赖SQLite的软件更贴合实际场景。通过理解OMIT与ENABLE两类宏，配合构建脚本、链接器裁剪和运行时验证，可以获得更少攻击面、更低资源占用并且仍然可靠的数据库层。
SQLite编译选项自定义构建SQLITE_OMIT修改时间：2026-08-25 20:17:56