尧图网站建设 
简介本资源为LZ4无损数据压缩算法的官方C语言源码包面向嵌入式开发、实时系统、网络传输等对压缩/解压性能敏感的中高级开发者解决跨平台快速集成轻量级压缩能力的问题。压缩包共11个文件6个头文件.h、5个实现文件.c包含核心压缩逻辑lz4.c/lz4hc.c、帧封装支持lz4frame.c/lz4frame.h、文件接口lz4file.c/h及哈希依赖xxhash.c/h总大小仅101KB结构精简可直接添加至任意C/C工程编译使用无需外部依赖。目前已有127人学习下载适合需要在Windows/Linux/macOS环境下快速验证压缩性能、定制内存或流式压缩逻辑、或为IoT设备裁剪压缩模块的开发者。读者可直接获取完整可编译源码树涵盖基础压缩、高压缩率模式HC、帧协议封装及文件级工具链支持具备生产环境集成所需的全部基础组件。 做底层数据的人基本都绕不开lz4这个名字。Yann Collet写的这个压缩算法在速度上几乎是“一脚油门到底”的风格——压缩起步就是400MB/s解压动不动上GB/s游戏热更新、嵌入式日志存储、数据库页压缩、网络协议传输里到处都有它的身影。但网上关于lz4的资料大多停留在“命令行怎么用”或者“pip装个库”真正想把源码直接添加到自己的工程编译、还要能裁剪定制的人反而很难找到一篇能照着走完的笔记。我最近刚好在一个跨平台嵌入式项目里做数据落盘前的快速压缩最后就是直接拿lz4源码进工程编译的。这篇我把从源码到固化进工程的全过程写出来文件结构、编译方式、API选型、坑点一次讲清楚。适合三类人看要把压缩功能塞进嵌入式板子的想用lz4替代既有压缩方案给传输提速的以及单纯想搞明白这套源码内部到底怎么组织的。1. 项目概述源码级集成LZ4到底拿它做什么1.1 什么场景下需要“源码直接编译”先说结论如果你只是想在PC上的Linux环境里调用压缩函数那装一下系统的liblz4-dev包就行根本不用费劲看源码。但一旦你遇到下面这些场景源码级集成就是唯一靠谱的路。第一类是嵌入式环境。很多RTOS、裸机工程、老款交叉编译工具链根本没有包管理器就算有你也不能保证目标板上能带动态库。源码编译进去是最确定的路径。第二类是定制裁剪。我的项目里只需要内存块压缩不需要lz4frame、不需要xxhash、不需要命令行工具如果把整个官方仓库不加区分地拖进工程代码体积和编译时间都会白白浪费。第三类是调试排障。数据解不出来的时候能直接断点到lz4.c里看它到底在哪个偏移量上匹配失败比在外面抱着一个黑盒库瞎猜要高效得多。第四类是规避动态库依赖。你发布一个可执行文件到客户机器上最怕的就是操作系统里某个库版本不对导致运行时报错把lz4静态编进自己的二进制省心不少。第五类就是纯粹学习想理解一个开源压缩算法的内部实现源码就在手边是最好的教材。1.2 这套源码能做什么边界在哪里先给不熟悉的同学补个定位。lz4是压缩算法不是一整个“压缩格式规范”。它自己定义了两层东西底层是块格式Block Format就是最简单的一次压缩一个内存块的编码上层是帧格式Frame Format相当于在块外面包了一层带魔数、块描述、校验和的容器也就是你在命令行工具里常见的 *.lz4 文件格式。如果你只是在程序内部压缩一段数据再自己解压块格式完全够用如果要和其他系统交换文件或者要兼容 lz4 命令行工具就得走 frame API。它和常见的压缩库定位差异很大我给个对比表格库压缩速度解压速度压缩率代码量典型场景lz4极快极快较低很小实时传输、嵌入式日志、游戏热更zlib中等中等中高中等网络协议、通用文件压缩zstd快很快高较大需要高压缩率但又想保留速度lz4的代码量小到可以直接编译进工程这是很多大型压缩库不具备的优势。核心文件就两三个 .c 文件编译出来占用也小这也是我最终选它而不是zstd的重要原因。2. LZ4核心原理与源码结构2.1 算法原理为什么它这么快lz4的核心思想是LZ77的变体。想象你在抄写一篇文章遇到一段前面已经抄过的内容不需要再逐字写只需要在纸上写一句“往前找从某某位置开始连着抄Y个字”。lz4做的事就是遍历输入数据时把最近的64KB历史数据存在一个滑动窗口里每到一个新位置用哈希表在历史窗口里查找有没有能匹配上的字符串。如果找到足够长的匹配至少4字节它就用一个很小的编码代替这一整串原始字节找不到就把当前字节原样输出。关键在细节。一个基本的token结构是第一个字节拆成高4位和低4位高4位表示后面有多少个字节是“原样拷贝”的字面量低4位表示匹配串长度在此基础上还要延长多少。之后跟着的是匹配偏移量通常2字节如果字面量长度或匹配长度超过了15还会继续用扩展字节来补。压缩器就是按照这个格式不断生成token流。lz4不像gzip那样为了更高压缩率去反复试探多种匹配策略、做上下文建模它只查一次哈希表就做决定所以压缩速度极其快。代价就是压缩率通常不如zlib但在很多场景下速度比压缩率值钱得多比如实时日志、网络包压缩、内存数据落盘。2.2 源码文件构成每个文件是干什么的lz4官方发布包里的源码目录看起来挺乱但核心文件其实就那么几个。我整理了一个文件清单方便你对照着选择需要加入工程的源文件文件作用依赖什么情况下需要lz4.c lz4.h核心块压缩、解压API无任何时候都需要lz4hc.c lz4hc.h高压缩率模式lz4.c的核心头文件对压缩率有更高要求时lz4frame.c lz4frame.h帧格式封装lz4.c xxhash需要生成/解析.lz4标准文件时xxhash.c xxhash.h快速哈希函数无被lz4frame依赖lz4file.c lz4file.h文件流封装lz4frame想要类似文件压缩接口时programs/lz4命令行工具源码以上全部需要独立命令行工具时如果你只是想编译一个最小可用版本只需要 lz4.c 和 lz4.h 两个文件就够了。我自己的项目就是这样日志数据在内部按块压缩完全不涉及文件格式所以 xxhash 和 frame 代码一个都没加进去。这个裁剪能力是官方库包直接给你的不用自己改源码只是选文件的问题。2.3 关键宏与编译参数源码里几个宏直接决定内存占用和压缩行为改之前一定要搞清楚它们是在哪个编译单元里生效的。LZ4_MEMORY_USAGE默认值是14。它决定压缩状态中的哈希表大小公式大约是 1 (LZ4_MEMORY_USAGE 2) 字节。默认14对应64KB左右的内存12对应16KB10对应4KB。如果你在内存紧张的MCU上跑可以把lz4.c编译时加上 -DLZ4_MEMORY_USAGE10把RAM占用压下来但压缩率会相应下降。LZ4_ACCELERATION_DEFAULT默认值是1。这个参数决定压缩时“加速”的程度加速值越大压缩器越不愿意花时间查更远、更长的匹配压缩速度更快但压缩率更低。65535是极限值基本就追着哈希表跑一圈就完事了。还有一个容易忽略的点这些宏通常是在 lz4.c 内部定义的你在头文件里改很可能不生效必须在编译 lz4.c 这一步传预定义宏或者直接改源码。这个细节踩过坑的人都知道如果你改完发现一点变化没有先检查自己的宏是不是被编译器看到了。3. 添加到工程编译三种可落地的集成方式3.1 方式一CMake直接引用源码如果工程使用的是CMake最省事的方式就是把lz4官方仓库放到third_party目录然后用add_subdirectory引进来。我在项目里是这么写的set(BUILD_TESTING OFF CACHE BOOL FORCE) set(LZ4_BUILD_CLI OFF CACHE BOOL FORCE) add_subdirectory(third_party/lz4) target_link_libraries(your_target PRIVATE lz4) target_include_directories(your_target PRIVATE third_party/lz4)LZ4_BUILD_CLI这个选项很关键它控制要不要编译命令行工具。默认可能是ON不关的话会多编译出一堆programs下的东西既拖慢构建又没意义。BUILD_TESTING也要关掉否则CMake配置阶段可能会尝试拉取测试依赖。如果你还在使用旧版本CMake可能没这个选项没关系直接跳过即可不影响主库编译。交叉编译场景下同样适用只要给你的CMake传入工具链文件add_subdirectory方式编译出来的静态库就直接是目标平台的。3.2 方式二手动把核心文件拖进工程很多IDE开发场景以及一部分MCU供应商提供的SDK工程根本不用CMake就是让你自己管理源文件。这时你只需要把 lz4.c、lz4.h 从 official release 包里拷贝进你的 third_party/lz4 目录然后在IDE里添加编译单元再把头文件搜索路径指过去。如果需要frame格式再加 lz4frame.c、lz4frame.h、xxhash.c、xxhash.h一个都不能少因为lz4frame依赖xxhash做校验和。这里有个容易忽略的C问题。如果你的工程是用C编译的包含lz4.h头文件的代码最好确保它走的是C链接。官方lz4.h自带 extern C 保护只要你别自己把lz4.c的声明单独抄出来基本不会遇到链接错误。另外lz4要求C99及以上标准老工程还在用C89的话要升一下编译标准否则 uint32_t 这些类型会一脸懵。3.3 方式三独立编译成静态库如果团队里多个项目要共用一份lz4我更推荐直接编译成独立静态库然后把 .a 文件和头文件丢给业务方省得每个工程重复编译。官方lib目录下自带Makefile直接支持这个目标cd lz4/lib make liblz4 CCaarch64-linux-gnu-gcc不加CC参数时用本机编译器得到本机静态库加交叉编译器的CC得到目标平台的静态库。编译产物通常是liblz4.a业务方只需要链接这个库并把 lz4.h 所在目录加入头文件搜索路径即可。做成静态库的好处是业务方不需要理解lz4源码组织结构SDK发布起来干净利落。3.4 用一个最小样例验证编译结果不管用哪种方式接进来第一步都应该先写一个最小程序验证库能不能用而不是直接塞进复杂业务代码里。下面这个例子虽然简单但把压缩、解压、缓冲区规划全走了#include stdio.h #include stdlib.h #include string.h #include lz4.h int main(void) { const char* src hello lz4, hello lz4, hello lz4!; int srcSize (int)strlen(src) 1; int maxDst LZ4_compressBound(srcSize); char* dst (char*)malloc(maxDst); char* back (char*)malloc(srcSize); int cSize LZ4_compress_default(src, dst, srcSize, maxDst); if (cSize 0) { printf(compress failed\n); return 1; } int rSize LZ4_decompress_safe(dst, back, cSize, srcSize); if (rSize 0) { printf(decompress failed\n); return 1; } printf(srcSize%d compressed%d restored%d strcmp%d\n, srcSize, cSize, rSize, strcmp(src, back)); free(dst); free(back); return 0; }这段代码里最重要的不是压缩本身而是back缓冲区必须给足srcSize。很多人第一次写lz4解压都栽在这个地方以为解压缓冲给多少都行结果返回值是负数。解压接口要求你恰好告诉它“解压后原始大小”它才能做边界检查。至于输出里compressed的具体数字跟lz4版本有关你只关心cSize大于0、rSize等于srcSize、strcmp等于0就说明链路通了。4. 核心API用法与实操要点4.1 单块压缩解压最常用的一组接口lz4最常用的一组API就是 LZ4_compress_default 和 LZ4_decompress_safe适合对一个完整内存块做一次性压缩。函数签名里藏着很多细节int LZ4_compress_default(const char* src, char* dst, int srcSize, int dstCapacity); int LZ4_decompress_safe(const char* src, char* dst, int compressedSize, int dstCapacity);压缩接口的srcSize是输入字节数dstCapacity是你给输出缓冲区分配的最大容量。官方建议用 LZ4_compressBound(inputSize) 来算最大压缩后体积公式是 inputSize inputSize/255 16也就是说最坏情况下输出比输入多一点点。这也很好理解如果输入数据完全没有重复lz4的token编码会把原始数据照抄一遍再附加一些控制字节所以输出反而略大于输入。解压接口的dstCapacity是目标缓冲区的容量而不是压缩数据的长度。它要求你传入“解压后的预期大小”压缩数据的大小由compressedSize单独给出。为什么反复强调这个因为 LZ4_decompress_safe 内部会拿着dstCapacity做边界检测如果实际需要的解压空间比它大它就返回一个负数表示失败而不是傻乎乎的越界写内存。这是安全版本和老的 fast 版本最大的区别。新版已经不建议用LZ4_decompress_fast了因为fast版本要求调用者绝对保证缓冲大小足够一旦猜错就可能造成缓冲区溢出。实际性能差异很小安全版本完全够用。4.2 流式压缩大块连续数据的正确姿势一次性压缩整块内存没有问题但如果数据是持续生产的比如日志流、网络包、传感器连续输出每次都攒到一大块再压缩内存开销和延迟都受不了。这时候要用流式接口。流式压缩的思路是维护一个LZ4_stream_t上下文把前一次压缩的数据窗口保留下来后续块能引用前面已经压缩过的内容从而获得更好的压缩率。基本流程是LZ4_stream_t* stream LZ4_createStream(); char* dst malloc(LZ4_compressBound(BLOCK_SIZE)); while (1) { int n read_block(src, buf, BLOCK_SIZE); if (n 0) break; int cSize LZ4_compress_continue(stream, buf, dst, n, LZ4_compressBound(BLOCK_SIZE)); // 把 dst 中的 cSize 字节发送出去 } LZ4_freeStream(stream);对应解压端用 LZ4_createStreamDecode 和 LZ4_decompress_safe_continue 来还原。这里有个容易误解的地方流式API不会替你做“网络封包”每次压缩出来的数据块边界要你自己管理比如在每个压缩块前面加一个4字节长度头否则解压端不知道每块多大。流式连续调用时千万不能每压缩一块就重新createStream一次不然前一块的数据窗口全部丢失压缩率会肉眼可见地下降。4.3 高压缩率模式 LZ4HC默认API追求速度压缩率只能说够用。如果希望体积更小一点lz4还提供了HC模式也就是 high compression。它的入口是int LZ4_compress_HC(const char* src, char* dst, int srcSize, int dstCapacity, int compressionLevel);compressionLevel范围是1到12官方建议0会被当成默认值9来理解等级越高压缩率越好但压缩速度会下降。注意HC模式只是压缩端更卖力解压端不需要任何额外逻辑因为解压格式和普通块完全一致。所以你可以只在写数据端用HC读数据端还是普通解压接口两边兼容。如果频繁调用压缩不要每次都让库去分配内部上下文用 LZ4_compress_HC_extStateHC 传入你自己的buffer承担状态空间能明显减少开销。HC模式适合对体积敏感但压缩频率不高的场景比如冷数据归档、安装包生成。4.4 Frame格式与命令行工具无缝兼容如果你只是内部自己压缩自己解压块API配合一个4字节长度前缀非常方便。但当你需要生成能被 lz4 命令行工具、其他语言库直接识别的数据时就必须用frame API。frame格式相当于给压缩数据包了一层外皮里面包含了魔数、版本、块大小、内容原始大小、校验和等元数据。最简单的压缩入口是#include lz4frame.h size_t bound LZ4F_compressFrameBound(srcSize, NULL); char* out malloc(bound); size_t outSize LZ4F_compressFrame(out, bound, src, srcSize, NULL);LZ4F_compressFrame 会一口气把整个内存块变成标准frame头部信息自己生成。解压端相对繁琐是迭代式的要创建 LZ4F_decompressionContext_t 上下文然后多次调用 LZ4F_decompress根据返回值判断是否处理完整。为什么复杂因为frame格式设计成支持流式、分块、动态长度解压端没法像块API那样一次拿到完整输出。这里我给个建议如果只是内部使用完全没必要用frame它最大的价值只是跨系统兼容性和自描述能力。5. 常见问题与排查技巧5.1 编译链接错误速查我把实际工程里遇到的和同行群里看过的典型错误汇总成一张表错误现象原因解决办法undefined reference toLZ4_compress_default只include了头文件没有把lz4.c加入编译或没链接库检查工程添加了lz4.c或链接liblz4.a重复定义符号lz4.c被多次加入编译单元去工程设置里确认源文件只添加了一次unknown type name uint32_t编译器不是C99模式或缺少stdint.h开C99/C11必要时加 -stdgnu99C工程链接失败extern C没生效确认包含的是官方lz4.h别自己声明函数编译超慢工程把lz4.c和lz4hc.c都编进去且开高优化如果不用HC直接移除lz4hc.c这些错误里我遇到过最阴间的就是“重复定义”。某些IDE会自动把目录下所有.c文件加进构建如果你把整个lz4目录直接拖进去programs目录下的源文件也会被一起编译一堆main符号冲突。所以手动添加时一定只选择lib目录下需要的文件。5.2 解压缓冲区大小经典中的经典坑很多人在项目上线后遇到“偶发解压失败”最后定位原因几乎都是同一个解压端不知道原始数据有多大。块API的 LZ4_decompress_safe 虽然安全但它要的是预期的原始大小而不是压缩后的大小。一旦传入的dstCapacity小于实际需要解压直接失败而且数据损坏时也会返回负数排查起来极具迷惑性。工程上的标准解法是自己封装一层协议在压缩后的数据最前面用4字节记录原始大小。我实际用的封包模式是这样// 压缩端 uint32_t rawSize htonl((uint32_t)srcSize); memcpy(out, rawSize, 4); int cSize LZ4_compress_default(src, out 4, srcSize, cap - 4); // 真正写入文件/网络的数据长度是 cSize 4 // 解压端 uint32_t rawSize ntohl(*(uint32_t*)in); char* out malloc(rawSize); int rSize LZ4_decompress_safe(in 4, out, totalLen - 4, rawSize);注意字节序转换int的大小在不同平台还不同我一般统一用uint32_t。这个4字节前缀方案虽然土但是稳。它也让解压端天然知道自己该分配多大的缓冲区从根上杜绝了缓冲区爆炸问题。5.3 性能调优与内存取舍lz4的默认参数并不总是最优解。压缩文本、JSON、配置这种高重复性数据时官方默认的acceleration1会花较多时间找最长匹配实际压缩率收益并不大。我用 LZ4_compress_fast 把acceleration调到2到5之后压缩速度提升三成以上压缩率只损失一两个百分点性价比极高。如果你对数据压缩率心里没底可以先拿一段真实数据跑一轮对比选择拐点处的参数。内存方面需要特别提醒在新版本lz4里 LZ4_compress_default 内部会在调用栈上生成一个 LZ4_stream_t 状态对象默认参数下体积接近64KB。这在PC上毫无感觉但在栈只有4KB的MCU上直接调用十有八九直接爆栈。嵌入式场景第一条铁律是不要用默认入口要自己持有状态用 LZ4_compress_fast_extState 或者 LZ4_compress_destSize 传入外部缓冲区。我早期踩过这个坑板子一跑压缩任务就进HardFault查了半天才发现是栈被压爆了。5.4 移植到裸机/RTOS的裁剪经验如果你的目标是裸机工程建议只拷贝 lz4.c 和 lz4.h 两个文件不用碰frame和HC。编译时用 -DLZ4_MEMORY_USAGE10 把哈希表内存降到4KB级别。解压端的 LZ4_decompress_safe 不需要复杂状态在极低RAM的板子上也能跑。如果还需要更小的RAM占用可以自行分配压缩状态不要让API在栈上创建。你可以先在自己PC上交叉编译一个最小固件对比编译出的镜像大小和RAM占用再决定要不要进一步裁剪。多说一条经验lz4.c本身是纯C、无平台相关代码我试过在x86、ARM Cortex-A、Cortex-M三类平台编译基本不用改源码本文还有配套的精品资源点击获取 LZ4源码级集成实战：原理、编译与嵌入式裁剪全解析
简介本资源为LZ4无损数据压缩算法的官方C语言源码包面向嵌入式开发、实时系统、网络传输等对压缩/解压性能敏感的中高级开发者解决跨平台快速集成轻量级压缩能力的问题。压缩包共11个文件6个头文件.h、5个实现文件.c包含核心压缩逻辑lz4.c/lz4hc.c、帧封装支持lz4frame.c/lz4frame.h、文件接口lz4file.c/h及哈希依赖xxhash.c/h总大小仅101KB结构精简可直接添加至任意C/C工程编译使用无需外部依赖。目前已有127人学习下载适合需要在Windows/Linux/macOS环境下快速验证压缩性能、定制内存或流式压缩逻辑、或为IoT设备裁剪压缩模块的开发者。读者可直接获取完整可编译源码树涵盖基础压缩、高压缩率模式HC、帧协议封装及文件级工具链支持具备生产环境集成所需的全部基础组件。 做底层数据的人基本都绕不开lz4这个名字。Yann Collet写的这个压缩算法在速度上几乎是“一脚油门到底”的风格——压缩起步就是400MB/s解压动不动上GB/s游戏热更新、嵌入式日志存储、数据库页压缩、网络协议传输里到处都有它的身影。但网上关于lz4的资料大多停留在“命令行怎么用”或者“pip装个库”真正想把源码直接添加到自己的工程编译、还要能裁剪定制的人反而很难找到一篇能照着走完的笔记。我最近刚好在一个跨平台嵌入式项目里做数据落盘前的快速压缩最后就是直接拿lz4源码进工程编译的。这篇我把从源码到固化进工程的全过程写出来文件结构、编译方式、API选型、坑点一次讲清楚。适合三类人看要把压缩功能塞进嵌入式板子的想用lz4替代既有压缩方案给传输提速的以及单纯想搞明白这套源码内部到底怎么组织的。1. 项目概述源码级集成LZ4到底拿它做什么1.1 什么场景下需要“源码直接编译”先说结论如果你只是想在PC上的Linux环境里调用压缩函数那装一下系统的liblz4-dev包就行根本不用费劲看源码。但一旦你遇到下面这些场景源码级集成就是唯一靠谱的路。第一类是嵌入式环境。很多RTOS、裸机工程、老款交叉编译工具链根本没有包管理器就算有你也不能保证目标板上能带动态库。源码编译进去是最确定的路径。第二类是定制裁剪。我的项目里只需要内存块压缩不需要lz4frame、不需要xxhash、不需要命令行工具如果把整个官方仓库不加区分地拖进工程代码体积和编译时间都会白白浪费。第三类是调试排障。数据解不出来的时候能直接断点到lz4.c里看它到底在哪个偏移量上匹配失败比在外面抱着一个黑盒库瞎猜要高效得多。第四类是规避动态库依赖。你发布一个可执行文件到客户机器上最怕的就是操作系统里某个库版本不对导致运行时报错把lz4静态编进自己的二进制省心不少。第五类就是纯粹学习想理解一个开源压缩算法的内部实现源码就在手边是最好的教材。1.2 这套源码能做什么边界在哪里先给不熟悉的同学补个定位。lz4是压缩算法不是一整个“压缩格式规范”。它自己定义了两层东西底层是块格式Block Format就是最简单的一次压缩一个内存块的编码上层是帧格式Frame Format相当于在块外面包了一层带魔数、块描述、校验和的容器也就是你在命令行工具里常见的 *.lz4 文件格式。如果你只是在程序内部压缩一段数据再自己解压块格式完全够用如果要和其他系统交换文件或者要兼容 lz4 命令行工具就得走 frame API。它和常见的压缩库定位差异很大我给个对比表格库压缩速度解压速度压缩率代码量典型场景lz4极快极快较低很小实时传输、嵌入式日志、游戏热更zlib中等中等中高中等网络协议、通用文件压缩zstd快很快高较大需要高压缩率但又想保留速度lz4的代码量小到可以直接编译进工程这是很多大型压缩库不具备的优势。核心文件就两三个 .c 文件编译出来占用也小这也是我最终选它而不是zstd的重要原因。2. LZ4核心原理与源码结构2.1 算法原理为什么它这么快lz4的核心思想是LZ77的变体。想象你在抄写一篇文章遇到一段前面已经抄过的内容不需要再逐字写只需要在纸上写一句“往前找从某某位置开始连着抄Y个字”。lz4做的事就是遍历输入数据时把最近的64KB历史数据存在一个滑动窗口里每到一个新位置用哈希表在历史窗口里查找有没有能匹配上的字符串。如果找到足够长的匹配至少4字节它就用一个很小的编码代替这一整串原始字节找不到就把当前字节原样输出。关键在细节。一个基本的token结构是第一个字节拆成高4位和低4位高4位表示后面有多少个字节是“原样拷贝”的字面量低4位表示匹配串长度在此基础上还要延长多少。之后跟着的是匹配偏移量通常2字节如果字面量长度或匹配长度超过了15还会继续用扩展字节来补。压缩器就是按照这个格式不断生成token流。lz4不像gzip那样为了更高压缩率去反复试探多种匹配策略、做上下文建模它只查一次哈希表就做决定所以压缩速度极其快。代价就是压缩率通常不如zlib但在很多场景下速度比压缩率值钱得多比如实时日志、网络包压缩、内存数据落盘。2.2 源码文件构成每个文件是干什么的lz4官方发布包里的源码目录看起来挺乱但核心文件其实就那么几个。我整理了一个文件清单方便你对照着选择需要加入工程的源文件文件作用依赖什么情况下需要lz4.c lz4.h核心块压缩、解压API无任何时候都需要lz4hc.c lz4hc.h高压缩率模式lz4.c的核心头文件对压缩率有更高要求时lz4frame.c lz4frame.h帧格式封装lz4.c xxhash需要生成/解析.lz4标准文件时xxhash.c xxhash.h快速哈希函数无被lz4frame依赖lz4file.c lz4file.h文件流封装lz4frame想要类似文件压缩接口时programs/lz4命令行工具源码以上全部需要独立命令行工具时如果你只是想编译一个最小可用版本只需要 lz4.c 和 lz4.h 两个文件就够了。我自己的项目就是这样日志数据在内部按块压缩完全不涉及文件格式所以 xxhash 和 frame 代码一个都没加进去。这个裁剪能力是官方库包直接给你的不用自己改源码只是选文件的问题。2.3 关键宏与编译参数源码里几个宏直接决定内存占用和压缩行为改之前一定要搞清楚它们是在哪个编译单元里生效的。LZ4_MEMORY_USAGE默认值是14。它决定压缩状态中的哈希表大小公式大约是 1 (LZ4_MEMORY_USAGE 2) 字节。默认14对应64KB左右的内存12对应16KB10对应4KB。如果你在内存紧张的MCU上跑可以把lz4.c编译时加上 -DLZ4_MEMORY_USAGE10把RAM占用压下来但压缩率会相应下降。LZ4_ACCELERATION_DEFAULT默认值是1。这个参数决定压缩时“加速”的程度加速值越大压缩器越不愿意花时间查更远、更长的匹配压缩速度更快但压缩率更低。65535是极限值基本就追着哈希表跑一圈就完事了。还有一个容易忽略的点这些宏通常是在 lz4.c 内部定义的你在头文件里改很可能不生效必须在编译 lz4.c 这一步传预定义宏或者直接改源码。这个细节踩过坑的人都知道如果你改完发现一点变化没有先检查自己的宏是不是被编译器看到了。3. 添加到工程编译三种可落地的集成方式3.1 方式一CMake直接引用源码如果工程使用的是CMake最省事的方式就是把lz4官方仓库放到third_party目录然后用add_subdirectory引进来。我在项目里是这么写的set(BUILD_TESTING OFF CACHE BOOL FORCE) set(LZ4_BUILD_CLI OFF CACHE BOOL FORCE) add_subdirectory(third_party/lz4) target_link_libraries(your_target PRIVATE lz4) target_include_directories(your_target PRIVATE third_party/lz4)LZ4_BUILD_CLI这个选项很关键它控制要不要编译命令行工具。默认可能是ON不关的话会多编译出一堆programs下的东西既拖慢构建又没意义。BUILD_TESTING也要关掉否则CMake配置阶段可能会尝试拉取测试依赖。如果你还在使用旧版本CMake可能没这个选项没关系直接跳过即可不影响主库编译。交叉编译场景下同样适用只要给你的CMake传入工具链文件add_subdirectory方式编译出来的静态库就直接是目标平台的。3.2 方式二手动把核心文件拖进工程很多IDE开发场景以及一部分MCU供应商提供的SDK工程根本不用CMake就是让你自己管理源文件。这时你只需要把 lz4.c、lz4.h 从 official release 包里拷贝进你的 third_party/lz4 目录然后在IDE里添加编译单元再把头文件搜索路径指过去。如果需要frame格式再加 lz4frame.c、lz4frame.h、xxhash.c、xxhash.h一个都不能少因为lz4frame依赖xxhash做校验和。这里有个容易忽略的C问题。如果你的工程是用C编译的包含lz4.h头文件的代码最好确保它走的是C链接。官方lz4.h自带 extern C 保护只要你别自己把lz4.c的声明单独抄出来基本不会遇到链接错误。另外lz4要求C99及以上标准老工程还在用C89的话要升一下编译标准否则 uint32_t 这些类型会一脸懵。3.3 方式三独立编译成静态库如果团队里多个项目要共用一份lz4我更推荐直接编译成独立静态库然后把 .a 文件和头文件丢给业务方省得每个工程重复编译。官方lib目录下自带Makefile直接支持这个目标cd lz4/lib make liblz4 CCaarch64-linux-gnu-gcc不加CC参数时用本机编译器得到本机静态库加交叉编译器的CC得到目标平台的静态库。编译产物通常是liblz4.a业务方只需要链接这个库并把 lz4.h 所在目录加入头文件搜索路径即可。做成静态库的好处是业务方不需要理解lz4源码组织结构SDK发布起来干净利落。3.4 用一个最小样例验证编译结果不管用哪种方式接进来第一步都应该先写一个最小程序验证库能不能用而不是直接塞进复杂业务代码里。下面这个例子虽然简单但把压缩、解压、缓冲区规划全走了#include stdio.h #include stdlib.h #include string.h #include lz4.h int main(void) { const char* src hello lz4, hello lz4, hello lz4!; int srcSize (int)strlen(src) 1; int maxDst LZ4_compressBound(srcSize); char* dst (char*)malloc(maxDst); char* back (char*)malloc(srcSize); int cSize LZ4_compress_default(src, dst, srcSize, maxDst); if (cSize 0) { printf(compress failed\n); return 1; } int rSize LZ4_decompress_safe(dst, back, cSize, srcSize); if (rSize 0) { printf(decompress failed\n); return 1; } printf(srcSize%d compressed%d restored%d strcmp%d\n, srcSize, cSize, rSize, strcmp(src, back)); free(dst); free(back); return 0; }这段代码里最重要的不是压缩本身而是back缓冲区必须给足srcSize。很多人第一次写lz4解压都栽在这个地方以为解压缓冲给多少都行结果返回值是负数。解压接口要求你恰好告诉它“解压后原始大小”它才能做边界检查。至于输出里compressed的具体数字跟lz4版本有关你只关心cSize大于0、rSize等于srcSize、strcmp等于0就说明链路通了。4. 核心API用法与实操要点4.1 单块压缩解压最常用的一组接口lz4最常用的一组API就是 LZ4_compress_default 和 LZ4_decompress_safe适合对一个完整内存块做一次性压缩。函数签名里藏着很多细节int LZ4_compress_default(const char* src, char* dst, int srcSize, int dstCapacity); int LZ4_decompress_safe(const char* src, char* dst, int compressedSize, int dstCapacity);压缩接口的srcSize是输入字节数dstCapacity是你给输出缓冲区分配的最大容量。官方建议用 LZ4_compressBound(inputSize) 来算最大压缩后体积公式是 inputSize inputSize/255 16也就是说最坏情况下输出比输入多一点点。这也很好理解如果输入数据完全没有重复lz4的token编码会把原始数据照抄一遍再附加一些控制字节所以输出反而略大于输入。解压接口的dstCapacity是目标缓冲区的容量而不是压缩数据的长度。它要求你传入“解压后的预期大小”压缩数据的大小由compressedSize单独给出。为什么反复强调这个因为 LZ4_decompress_safe 内部会拿着dstCapacity做边界检测如果实际需要的解压空间比它大它就返回一个负数表示失败而不是傻乎乎的越界写内存。这是安全版本和老的 fast 版本最大的区别。新版已经不建议用LZ4_decompress_fast了因为fast版本要求调用者绝对保证缓冲大小足够一旦猜错就可能造成缓冲区溢出。实际性能差异很小安全版本完全够用。4.2 流式压缩大块连续数据的正确姿势一次性压缩整块内存没有问题但如果数据是持续生产的比如日志流、网络包、传感器连续输出每次都攒到一大块再压缩内存开销和延迟都受不了。这时候要用流式接口。流式压缩的思路是维护一个LZ4_stream_t上下文把前一次压缩的数据窗口保留下来后续块能引用前面已经压缩过的内容从而获得更好的压缩率。基本流程是LZ4_stream_t* stream LZ4_createStream(); char* dst malloc(LZ4_compressBound(BLOCK_SIZE)); while (1) { int n read_block(src, buf, BLOCK_SIZE); if (n 0) break; int cSize LZ4_compress_continue(stream, buf, dst, n, LZ4_compressBound(BLOCK_SIZE)); // 把 dst 中的 cSize 字节发送出去 } LZ4_freeStream(stream);对应解压端用 LZ4_createStreamDecode 和 LZ4_decompress_safe_continue 来还原。这里有个容易误解的地方流式API不会替你做“网络封包”每次压缩出来的数据块边界要你自己管理比如在每个压缩块前面加一个4字节长度头否则解压端不知道每块多大。流式连续调用时千万不能每压缩一块就重新createStream一次不然前一块的数据窗口全部丢失压缩率会肉眼可见地下降。4.3 高压缩率模式 LZ4HC默认API追求速度压缩率只能说够用。如果希望体积更小一点lz4还提供了HC模式也就是 high compression。它的入口是int LZ4_compress_HC(const char* src, char* dst, int srcSize, int dstCapacity, int compressionLevel);compressionLevel范围是1到12官方建议0会被当成默认值9来理解等级越高压缩率越好但压缩速度会下降。注意HC模式只是压缩端更卖力解压端不需要任何额外逻辑因为解压格式和普通块完全一致。所以你可以只在写数据端用HC读数据端还是普通解压接口两边兼容。如果频繁调用压缩不要每次都让库去分配内部上下文用 LZ4_compress_HC_extStateHC 传入你自己的buffer承担状态空间能明显减少开销。HC模式适合对体积敏感但压缩频率不高的场景比如冷数据归档、安装包生成。4.4 Frame格式与命令行工具无缝兼容如果你只是内部自己压缩自己解压块API配合一个4字节长度前缀非常方便。但当你需要生成能被 lz4 命令行工具、其他语言库直接识别的数据时就必须用frame API。frame格式相当于给压缩数据包了一层外皮里面包含了魔数、版本、块大小、内容原始大小、校验和等元数据。最简单的压缩入口是#include lz4frame.h size_t bound LZ4F_compressFrameBound(srcSize, NULL); char* out malloc(bound); size_t outSize LZ4F_compressFrame(out, bound, src, srcSize, NULL);LZ4F_compressFrame 会一口气把整个内存块变成标准frame头部信息自己生成。解压端相对繁琐是迭代式的要创建 LZ4F_decompressionContext_t 上下文然后多次调用 LZ4F_decompress根据返回值判断是否处理完整。为什么复杂因为frame格式设计成支持流式、分块、动态长度解压端没法像块API那样一次拿到完整输出。这里我给个建议如果只是内部使用完全没必要用frame它最大的价值只是跨系统兼容性和自描述能力。5. 常见问题与排查技巧5.1 编译链接错误速查我把实际工程里遇到的和同行群里看过的典型错误汇总成一张表错误现象原因解决办法undefined reference toLZ4_compress_default只include了头文件没有把lz4.c加入编译或没链接库检查工程添加了lz4.c或链接liblz4.a重复定义符号lz4.c被多次加入编译单元去工程设置里确认源文件只添加了一次unknown type name uint32_t编译器不是C99模式或缺少stdint.h开C99/C11必要时加 -stdgnu99C工程链接失败extern C没生效确认包含的是官方lz4.h别自己声明函数编译超慢工程把lz4.c和lz4hc.c都编进去且开高优化如果不用HC直接移除lz4hc.c这些错误里我遇到过最阴间的就是“重复定义”。某些IDE会自动把目录下所有.c文件加进构建如果你把整个lz4目录直接拖进去programs目录下的源文件也会被一起编译一堆main符号冲突。所以手动添加时一定只选择lib目录下需要的文件。5.2 解压缓冲区大小经典中的经典坑很多人在项目上线后遇到“偶发解压失败”最后定位原因几乎都是同一个解压端不知道原始数据有多大。块API的 LZ4_decompress_safe 虽然安全但它要的是预期的原始大小而不是压缩后的大小。一旦传入的dstCapacity小于实际需要解压直接失败而且数据损坏时也会返回负数排查起来极具迷惑性。工程上的标准解法是自己封装一层协议在压缩后的数据最前面用4字节记录原始大小。我实际用的封包模式是这样// 压缩端 uint32_t rawSize htonl((uint32_t)srcSize); memcpy(out, rawSize, 4); int cSize LZ4_compress_default(src, out 4, srcSize, cap - 4); // 真正写入文件/网络的数据长度是 cSize 4 // 解压端 uint32_t rawSize ntohl(*(uint32_t*)in); char* out malloc(rawSize); int rSize LZ4_decompress_safe(in 4, out, totalLen - 4, rawSize);注意字节序转换int的大小在不同平台还不同我一般统一用uint32_t。这个4字节前缀方案虽然土但是稳。它也让解压端天然知道自己该分配多大的缓冲区从根上杜绝了缓冲区爆炸问题。5.3 性能调优与内存取舍lz4的默认参数并不总是最优解。压缩文本、JSON、配置这种高重复性数据时官方默认的acceleration1会花较多时间找最长匹配实际压缩率收益并不大。我用 LZ4_compress_fast 把acceleration调到2到5之后压缩速度提升三成以上压缩率只损失一两个百分点性价比极高。如果你对数据压缩率心里没底可以先拿一段真实数据跑一轮对比选择拐点处的参数。内存方面需要特别提醒在新版本lz4里 LZ4_compress_default 内部会在调用栈上生成一个 LZ4_stream_t 状态对象默认参数下体积接近64KB。这在PC上毫无感觉但在栈只有4KB的MCU上直接调用十有八九直接爆栈。嵌入式场景第一条铁律是不要用默认入口要自己持有状态用 LZ4_compress_fast_extState 或者 LZ4_compress_destSize 传入外部缓冲区。我早期踩过这个坑板子一跑压缩任务就进HardFault查了半天才发现是栈被压爆了。5.4 移植到裸机/RTOS的裁剪经验如果你的目标是裸机工程建议只拷贝 lz4.c 和 lz4.h 两个文件不用碰frame和HC。编译时用 -DLZ4_MEMORY_USAGE10 把哈希表内存降到4KB级别。解压端的 LZ4_decompress_safe 不需要复杂状态在极低RAM的板子上也能跑。如果还需要更小的RAM占用可以自行分配压缩状态不要让API在栈上创建。你可以先在自己PC上交叉编译一个最小固件对比编译出的镜像大小和RAM占用再决定要不要进一步裁剪。多说一条经验lz4.c本身是纯C、无平台相关代码我试过在x86、ARM Cortex-A、Cortex-M三类平台编译基本不用改源码本文还有配套的精品资源点击获取