简介LibXL 4.1.1 是一份面向 C 开发者的 Excel 读写库安装与开发资料包适合需要在 Windows、Linux 跨平台项目中生成报表、导入导出表格数据的中高级开发者也可用于数据分析、报表生成与自动化测试等场景。压缩包共 726 个文件约 29.81MB包含 56 个 cpp、54 个 c、44 个 h 等源码与头文件21 个 sln、70 个 vcxproj 等工程配置另有 22 个 xls、5 个 xlsx 示例表格及 13 个 dll、6 个 lib 库文件兼顾编译验证、接口参考与示例运行目录结构便于按模块检索。目前已有 2070 人学习或下载。内容覆盖读取、写入、修改 XLS 以及跨平台使用场景配合示例工程和表格样例可帮助读者理解库的接口组织、工程配置与常见调用方式并对照排查 Windows 与 Linux 环境下的兼容性问题。标题中的注册信息与包内多语言示例也便于快速验证功能、评估项目适用性对希望在既有 C 项目中嵌入 Excel 处理能力的读者更有参考价值。1. libxl 4.1.1 是什么不装 Office 也能读写 xls/xlsx 的 C/C 库起因是帮人改一个导出模块设备上跑的是精简过的 Linux 系统没有 Office也没有 Python 环境每天要往一张 xls 记录表里追加几千行检测数据。原来的做法是用 shell 拼 CSV客户用 Excel 打开后中文列名全是乱码日期也变成 45000 这种数字。换成 libxl 4.1.1 之后一个两百来行的 C 程序就把这件事解决了——libxl 是纯 C/C 的 Excel 读写库直接生成和解析 xls、xlsx不依赖 Office也不依赖 COM在 Linux 下挂上一个 so 就能跑。这份 4.1.1 最新版带了注册信息按第 2 章讲的方式调用 setKey 之后才会解锁完整的写入能力。它适合三类人后端服务里要定时出报表的、桌面客户端里要加导出功能的以及在工控机、设备端读写记录表的。2. 把 libxl 4.1.1 接进工程目录、链接参数与注册信息的落位二进制分发包最容易翻车的地方不是 API而是环境搭建。头文件放在哪个目录、链接时写-lxl还是-llibxl、运行时 so 找不到、注册信息在什么时候调用才生效——这四个问题会消耗掉大半的调试时间。所以先把工程接起来接对了再谈功能。2.1 包里给了什么先ls一遍再动手这类二进制分发包的结构基本是固定的先确认三样东西C 头文件目录、C 接口头文件目录、以及对应架构的 so 文件。常见做法是这样路径内容你需要确认的事include_cpp/libxl.hC 接口Book、Sheet、Format类文件里有没有namespace libxlinclude_c/libxl.hC 接口BookHandle、xlCreateXMLBook等与 C 头文件同名不要混着 includelib64/libxl.so64 位动态库file lib64/libxl.so看是不是 x86-64/aarch64lib/libxl.so32 位动态库和设备端架构对上才有用先用file命令确认 so 的架构。我在一台 aarch64 的工控板上遇到过目录名叫lib64、里面装的却是 x86-64 的库链接能过运行时才报错排查花了不少时间。确认完架构再确认你项目里 include 的是 C 还是 C 的那份头文件——两份同名头文件的路径不能同时加进-I否则编译器取到哪一份全看参数顺序属于典型的玄学问题。如果编译器是 g、但项目主体是 C直接#include libxl.h走 C 接口就行链接时记得补-lstdc因为 libxl 内部是 C 实现的纯 gcc 链接会缺符号。2.2 CMake 与手工链接两条路都走一遍现代一点的工程用 CMake关键是 include 目录、链接目录、rpath 三项都要写全尤其是 rpath——不写的话编译期没问题、跑起来就报“找不到 so”。cmake_minimum_required(VERSION 3.10) project(xls_report CXX) set(CMAKE_CXX_STANDARD 11) # 把解压后的 libxl 放在工程内的 third_party 下避免依赖绝对路径 set(LIBXL_ROOT ${CMAKE_SOURCE_DIR}/third_party/libxl) add_executable(xls_report main.cpp) # 1) 头文件目录只加 C 那份别和 C 接口目录混用 target_include_directories(xls_report PRIVATE ${LIBXL_ROOT}/include_cpp) # 2) 库目录 库名libxl.so 对应 -lxl target_link_directories(xls_report PRIVATE ${LIBXL_ROOT}/lib64) target_link_libraries(xls_report PRIVATE xl stdc) # 3) rpath编译期和安装后都能找到 so set_target_properties(xls_report PROPERTIES BUILD_RPATH ${LIBXL_ROOT}/lib64 INSTALL_RPATH $ORIGIN/../lib64)target_link_libraries里的xl是从libxl.so反推出来的写成libxl会变成找liblibxl.so。$ORIGIN表示可执行文件自身所在目录配合../lib64就能做成“整个目录拷到设备上直接跑”的绿色部署不用动系统库路径。如果你不用 CMake等价的手工命令是g -stdc11 main.cpp -o xls_report \ -Ithird_party/libxl/include_cpp \ -Lthird_party/libxl/lib64 \ -lxl -lstdc \ -Wl,-rpath,$ORIGIN/../lib64-Wl,-rpath,后面单引号不能省否则 shell 会把$ORIGIN当变量展开成空串编出来的程序还是找不到库。这一点在写 CI 脚本时特别容易忘本地测试正常、打包后崩属于“血泪经验”级别的细节。2.3 第一段能跑的代码建表、写格子、落盘接口上手成本很低Book是工作簿Sheet是工作表行列下标从 0 开始。写一个最小可运行版本#include libxl.h #include cstdio using namespace libxl; int main() { // xlsx 用 xlCreateXMLBook老式 xls 用 xlCreateBook Book* book xlCreateXMLBook(); if (!book) { printf(create book failed\n); return 1; } // 注册信息必须在 load/save 之前设置见 2.4 book-setKey(L注册名, L注册码); Sheet* sheet book-addSheet(L检测台账); if (!sheet) { book-release(); return 1; } // 表头加粗格式对象只建一次后面复用 Format* head book-addFormat(); head-setBold(true); head-setAlignH(ALIGNH_CENTER); sheet-writeStr(0, 0, L产线, head); sheet-writeStr(0, 1, L检测时间, head); sheet-writeStr(0, 2, L读数, head); // 数据行行列都是 0 基第 0 行被表头占了 sheet-writeStr(1, 0, LA线); sheet-writeNum(1, 1, 45123.5); // Excel 的日期序列值 sheet-writeNum(1, 2, 12.34); sheet-setColWidth(0, 10); // 列宽按字符宽度算 sheet-setColWidth(1, 20); if (!book-save(Ldemo.xlsx)) { printf(save failed\n); book-release(); return 2; } book-release(); // 必须调用否则内存和临时文件都不释放 printf(ok\n); return 0; }有两个点第一次用会踩writeStr的字符串是库内部拷贝一份你传临时对象也没事但readStr返回的指针归库所有不能free也不要跨release持有。另外addFormat()属于book而不是sheet同一个book下的所有 sheet 共用格式对象是正常用法跨 book 复用就是野指针。2.4 注册信息放哪setKey 的时机与凭据管理包里的注册信息对应setKey(name, key)两个参数调用时机很关键必须在任何load或save之前。放在xlCreateXMLBook()之后第一行最稳妥晚了就会出现“写出来的文件内容正常、但带着未授权标记”的情况很多人以为是库坏了其实只是顺序问题。凭据本身不建议硬编码在源码里。我一般的做法是走环境变量配置文件也行但别进版本库#include cstdlib #include libxl.h // 从环境变量取注册信息源码里不留明文 bool applyLicense(libxl::Book* book) { const char* name std::getenv(LIBXL_NAME); const char* key std::getenv(LIBXL_KEY); if (!name || !key) return false; // 缺凭据就明确失败别静默降级 // char* 转宽字符依赖当前 locale启动时先 setlocale(LC_ALL, ) wchar_t wname[128] {0}, wkey[512] {0}; mbstowcs(wname, name, 127); mbstowcs(wkey, key, 511); return book-setKey(wname, wkey); }setKey返回 bool建议把返回值打进日志出问题时一眼能看出是凭据没生效还是别的环节挂了。这段代码里mbstowcs的转换结果依赖 locale所以程序启动时要先setlocale(LC_ALL, )不然中文注册名会转成空串。提示这份包里的注册信息属于随包附带的授权凭据交付给客户或提交到公共仓库前先确认授权范围凭据泄漏和代码泄漏是两回事。3. 读写 Excel 的核心 API单元格类型、日期基准与 Format 对象接口接好之后真正决定“导出能不能用”的是三件事写进去的类型对不对、读出来的时候判没判类型、格式对象有没有复用。这三件事在 libxl 里都有明确的 API但默认行为不一定符合直觉。3.1 四种写入原语什么时候用哪个libxl 的写入口就四个选错会直接体现在结果文件里方法写入内容典型误用writeStr文本强制按字符串存把12.34当数字写下游求和全是 0writeNum双精度数字写日期忘了配NUMFORMAT_DATE显示成 45123writeBool布尔值用writeStr(true)Excel 里无法筛选writeFormula公式串不带等号带上前缀被当成文本原样显示writeFormula有个必须知道的行为libxl 只负责把公式写进去不会替 Excel 算出结果缓存值这一栏是空的。用 Excel 打开会自动重算但很多在线预览、服务端解析器、以及某些报表工具读的是缓存值就会显示 0 或空白。常见做法是公式和数值各写一份——公式放在隐藏列供人核对数值放在可见列给机器读或者导出后强制下游重算一次。// 公式不带等号同时把算好的值写到相邻单元格兼容不重算的读取方 sheet-writeFormula(2, 3, LSUM(D1:D2), nullptr); sheet-writeNum(2, 4, 24.68); // 与公式结果保持一致供机器读取3.2 读的时候先判类型别直接 readStr读表格最常见的写法是readStr一行行扫遇到空单元格返回 NULL遇到数字返回的是格式化后的字符串。问题在于日期、百分比、千分位这些格式会把原始值伪装起来你拿到的12.34%没法直接参与计算。稳妥的顺序是先判类型再决定用哪个读法。// 遍历时先看 cellType再决定用 readStr 还是 readNum for (int r 0; r sheet-lastRow(); r) { for (int c 0; c sheet-lastCol(); c) { CellType t sheet-cellType(r, c); if (t CELLTYPE_EMPTY || t CELLTYPE_BLANK) continue; if (t CELLTYPE_NUMBER) { if (sheet-isDate(r, c)) { // 日期格拿原始序列值再解包别用字符串 double d sheet-readNum(r, c); int y 0, m 0, day 0; book-dateUnpack(d, y, m, day); printf(%04d-%02d-%02d\n, y, m, day); } else { printf(%.4f\n, sheet-readNum(r, c)); } } else if (t CELLTYPE_STRING) { const wchar_t* s sheet-readStr(r, c); if (s) printf(%ls\n, s); // 指针归库所有不要 free } } }lastRow()和lastCol()返回的是“有内容的边界”不是整张表的行列数所以用它们做循环上界比硬编码安全。isDate必须和cellType CELLTYPE_NUMBER配合使用——日期在文件里本质就是个数字只有格式信息才能区分它到底是日期还是普通小数。3.3 日期为什么读出来是 450001900 基准与 datePackExcel 的日期是一个从 1900-01-00 起算的序列号45000大约对应 2023 年 3 月。所以直接readNum拿到日期格得到的一定是个四五万的小数小数部分就是时分秒。反过来写日期也一样writeNum写进去的只是一个数不配格式就永远不会显示成日期。// 写日期先打包成序列值再配日期格式 Format* dateFmt book-addFormat(); dateFmt-setNumFormat(NUMFORMAT_DATE); // 预定义常量够用就别自定义 double d book-datePack(2024, 3, 15, 8, 30, 0); // 年月日时分秒 sheet-writeNum(3, 1, d, dateFmt);datePack返回的序列值和 Excel 内部表示一致跨平台换算时区问题由你自己在上层处理——libxl 不做时区转换它只做序列值和年月日之间的算术。这一点在跨时区部署的服务上要特别注意同一份数据在东八区导出、在 UTC 机器上读回来日期可能差一天。常见做法是统一按业务时区打包读的时候也按同一时区解包中间不做本地时间转换。3.4 Format 对象数字格式、列宽与换行Format是控制“看起来怎么样”的唯一入口一次addFormat()拿到一个对象之后用 setter 逐项配置。常用的几项方法作用备注setNumFormat(...)数字/日期格式可用预定义常量也可传自定义格式串setAlignH/setAlignV水平/垂直对齐表头居中用得多setWrap(true)自动换行长文本列必开否则打印被截断setBold/setFont字体字体对象用book-addFont()单独建setBorder(...)边框报表类需求常用四边细线// 字体对象单独创建再挂到 Format 上两者都归 book 所有 Font* f book-addFont(); f-setName(L宋体); f-setSize(11); Format* cell book-addFormat(); cell-setFont(f); cell-setWrap(true); cell-setAlignV(ALIGNV_CENTER); cell-setNumFormat(L0.00); // 自定义两位小数自定义格式串的语法跟 Excel 的“设置单元格格式”完全一致0.00、#,##0、yyyy-mm-dd hh:mm都能直接传。列宽用setColWidth单位是字符宽度默认列宽大约 8.43超过 20 的中文列建议配合setWrap一起用。4. 批量导出与内存账4.1.1 在大表场景下的用法小表怎么写都行几千行以上就要开始算账了。libxl 的工作方式是整本加载进内存没有逐行流式写出这意味着内存占用跟表的大小是线性关系而且系数不小。这一章讲清楚开销在哪、怎么省。4.1 每格一个 Format 是最大的性能杀手新手写法容易在循环里book-addFormat()写一万行就建了一万个格式对象。这些对象在保存时要逐个序列化进 xlsx 的样式表文件体积可能翻好几倍保存耗时也从毫秒级涨到秒级。// 反例循环里创建格式对象 for (int r 1; r 10000; r) { Format* f book-addFormat(); // 一万个对象全部写进 styles.xml f-setNumFormat(L0.00); sheet-writeNum(r, 2, data[r], f); } // 正例格式对象在循环外建好循环内只传指针 Format* numFmt book-addFormat(); numFmt-setNumFormat(L0.00); for (int r 1; r 10000; r) { sheet-writeNum(r, 2, data[r], numFmt); }原理很简单xlsx 是一堆 XML 打包成的 zipxl/styles.xml里记录所有格式定义单元格只存一个索引。格式对象越少样式表越小序列化越快。我一般把格式收拢成一张“格式表”在初始化阶段一次性建好后面按枚举取用。4.2 内存占用估算与“分段落盘”的做法libxl 读 xlsx 时会把整本解析成内存对象树实际占用大概是文件体积的十几到二十几倍一个 20MB 的 xlsx峰值可能吃掉 400MB 以上如果只是读一个 sheet 里的几列这个代价就很难接受。没有流式接口的情况下实用的办法是“切分输入”按 sheet 拆成多个文件、按行数分成多个分片、或者让上游直接产出多个小文件再逐个处理。处理完一个release()一个不要在一个进程里同时持有两个Book。// 分片处理的骨架读一个、写一个、立刻释放 for (const auto part : parts) { // parts 是分片文件路径列表 Book* in xlCreateXMLBook(); in-setKey(name, key); if (!in-load(part.c_str())) { in-release(); continue; } Book* out xlCreateXMLBook(); out-setKey(name, key); Sheet* os out-addSheet(L汇总); // ……搬运并计算…… out-save(outPath.c_str()); out-release(); in-release(); // 关键下一个分片开始前释放 }这段骨架里release()的位置是重点。放在循环外内存会随分片数量单调增长放在save之后、下一个load之前峰值就稳定在单个分片的量级上。4.3 一个可复用的导出封装把上面这些收拢成一个类业务侧只需要填数据不用关心格式和释放class XlsWriter { public: XlsWriter(const wchar_t* name, const wchar_t* key) { book_ xlCreateXMLBook(); book_-setKey(name, key); sheet_ book_-addSheet(L数据); // 格式一次性建好全生命周期复用 fmtHeader_ book_-addFormat(); fmtHeader_-setBold(true); fmtHeader_-setAlignH(ALIGNH_CENTER); fmtNum_ book_-addFormat(); fmtNum_-setNumFormat(L0.00); } ~XlsWriter() { if (book_) book_-release(); } // RAII异常路径也释放 XlsWriter(const XlsWriter) delete; XlsWriter operator(const XlsWriter) delete; void header(int c, const wchar_t* text) { sheet_-writeStr(0, c, text, fmtHeader_); } void number(int r, int c, double v) { sheet_-writeNum(r, c, v, fmtNum_); } bool save(const wchar_t* path) { return book_-save(path); } private: Book* book_ nullptr; Sheet* sheet_ nullptr; Format* fmtHeader_ nullptr; Format* fmtNum_ nullptr; };析构里release()是必须的不只是为了内存——libxl 在保存 xlsx 时会用到临时资源不释放的进程在长期运行的守护服务里会缓慢泄漏。禁掉拷贝构造是为了防止两个对象持有同一个Book*那会直接导致二次释放崩溃。5. 五个高频翻车点从现象到原因到解法这些问题在邮件列表和代码托管平台的讨论里反复出现基本都是环境或语义理解偏差导致的不是库本身有 bug。5.1 中文列名变成问号或空串现象Windows 上编译运行正常代码原样拷到 Linux 上写出来的中文全是问号或者干脆是空字符串。原因wchar_t在两个平台上的宽度不一样Windows 是 2 字节UTF-16Linux 一般是 4 字节UTF-32。如果你的代码里用了wcslen、sizeof之类的操作去构造字符串或者手动做了宽窄字符转换跨平台就会错位。另外进程启动时没有setlocale宽字符输出到终端或转成路径时也会失效。解决统一用L字面量让编译器按当前平台的宽度生成跨平台层如果需要拼字符串用标准库的std::wstring而不是手工算长度程序入口加一行setlocale(LC_ALL, )中文文件名和中文输出才能正常。5.2 日期读回来是 45123.5 这种数字现象用readNum拿日期格得到的是一串四五万的数字直接当日期显示就成了天文数字。原因Excel 里日期就是数字加格式readNum拿的是原始序列值没有经过格式解释。isDate才是判断依据。解决读之前先if (sheet-isDate(r, c))再用dateUnpack拆成时分秒。写的时候反过来datePack打包成序列值再挂一个NUMFORMAT_DATE的格式对象两步缺一不可。5.3 公式写进去了打开显示 0 或者空白现象writeFormula之后用 Excel 打开没问题但换成在线预览、服务端解析库、或者某些报表工具读到的值是 0。原因libxl 只写公式文本不计算公式结果缓存值那一栏是空的。Excel 打开时会自动重算不重算的读取方就只能拿到空值。解决公式和结果同时写——公式放一列供人核对数值放另一列给机器读或者在下游导入时显式触发一次重算。对服务端解析场景建议直接写数值公式只在给人看的版本里保留。5.4 运行时报libxl.so: cannot open shared object file现象编译链接全部通过程序一启动就报找不到动态库用ldd看是not found。原因三种可能——rpath 没写或写错$ORIGIN被 shell 展开了so 的架构和可执行文件不匹配或者把库拷到了设备上但路径和编译时不一样。解决先用file确认架构一致再用ldd ./程序看它到底在找哪个路径临时验证用LD_LIBRARY_PATH./lib64 ./程序长期方案是把 rpath 写进编译参数。发布包里把 so 和可执行文件放成固定相对位置比依赖系统路径靠谱得多。5.5 保存返回失败或者文件存出来打不开现象save()返回 false或者返回 true 但生成的文件用 Excel 打开提示损坏。原因目标路径被占用文件正被 Excel 或 WPS 打开、目录没有写权限、中文文件名在非 UTF-8 locale 下转换失败、以及没有先setKey导致写出的文件不完整。解决先看save的返回值而不是假设成功接着确认目录权限和文件占用文件名尽量用 ASCII一定要用中文就把 locale 设成 UTF-8最后确认setKey在所有load/save之前。这四条按顺序查基本能覆盖九成问题。6. 五分钟自检确认手上的 4.1.1 是完整可用的一份拿到一个带注册信息的二进制库最怕的是“看着能用、关键功能缺一块”。我习惯先跑一个自检程序把中文、日期、公式、格式、合并单元格这五样全写一遍再用另一条技术路线读回来交叉验证——自己能读出来不算数别人能读出来才算。第一步用 2.3 那段代码改一版故意把这五个特性都塞进去// 自检用五类特性各写一处任何一项失败都能定位 sheet-writeStr(0, 0, L中文表头, fmtHeader_); // 1 中文 sheet-writeNum(1, 0, book-datePack(2024, 3, 15, 8, 30, 0), fmtDate_); // 2 日期 sheet-writeFormula(2, 0, LSUM(B1:B2), nullptr); // 3 公式 sheet-writeNum(3, 0, 1234.5678, fmtNum_); // 4 数字格式 sheet-mergeCells? // 5 合并单元格第二步别只用自己的库验证换成完全独立的一条链路读回来# 1) xlsx 本质是 zip先看结构完整不完整 unzip -l out.xlsx | grep -E sharedStrings|styles|sheet1 # 2) 抽出共享字符串表确认中文是 UTF-8 而不是问号 unzip -p out.xlsx xl/sharedStrings.xml | head -c 400 # 3) 用另一套技术栈读回来做字段级比对仅验证用不进生产 python3 - PY import openpyxl wb openpyxl.load_workbook(out.xlsx) ws wb.active print(repr(ws[A1].value), ws[A2].value, ws[A3].value, ws[A4].value) PY第三步把结果对到下面这张表上哪一行不符就回到对应章节查检查项期望结果不符时先怀疑中文表头读回来是完整中文不是?或空5.1 字符宽度与 locale日期格读回来是 2024-03-15不是 453665.2 少了 isDate 或格式对象公式缓存值不为空或下游能重算5.3 只写了公式没写值数字格式文件里显示两位小数setNumFormat传的是常量还是字符串合并单元格结构表里有mergeCell节点单元格写入顺序是否在合并之后这套自检我一般会在接入当天跑完顺手把输出文件用表格软件打开看一眼渲染效果——有些问题列宽挤压、换行被截断、边框缺失只有肉眼看得见靠解析器读不出来。从那以后我每接一个新的二进制库都会先花五分钟把这张表跑一遍再动手写业务代码省下的返工时间远超这五分钟。这份 4.1.1 带上注册信息按 2.4 的方式配好凭据上面五类特性都能一次过值得收进工具箱备用。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/30 11:57:30 · 阅读 1.2k libxl 4.1.1 实战：Linux C/C++ 无 Office 读写 xls/xlsx
简介LibXL 4.1.1 是一份面向 C 开发者的 Excel 读写库安装与开发资料包适合需要在 Windows、Linux 跨平台项目中生成报表、导入导出表格数据的中高级开发者也可用于数据分析、报表生成与自动化测试等场景。压缩包共 726 个文件约 29.81MB包含 56 个 cpp、54 个 c、44 个 h 等源码与头文件21 个 sln、70 个 vcxproj 等工程配置另有 22 个 xls、5 个 xlsx 示例表格及 13 个 dll、6 个 lib 库文件兼顾编译验证、接口参考与示例运行目录结构便于按模块检索。目前已有 2070 人学习或下载。内容覆盖读取、写入、修改 XLS 以及跨平台使用场景配合示例工程和表格样例可帮助读者理解库的接口组织、工程配置与常见调用方式并对照排查 Windows 与 Linux 环境下的兼容性问题。标题中的注册信息与包内多语言示例也便于快速验证功能、评估项目适用性对希望在既有 C 项目中嵌入 Excel 处理能力的读者更有参考价值。1. libxl 4.1.1 是什么不装 Office 也能读写 xls/xlsx 的 C/C 库起因是帮人改一个导出模块设备上跑的是精简过的 Linux 系统没有 Office也没有 Python 环境每天要往一张 xls 记录表里追加几千行检测数据。原来的做法是用 shell 拼 CSV客户用 Excel 打开后中文列名全是乱码日期也变成 45000 这种数字。换成 libxl 4.1.1 之后一个两百来行的 C 程序就把这件事解决了——libxl 是纯 C/C 的 Excel 读写库直接生成和解析 xls、xlsx不依赖 Office也不依赖 COM在 Linux 下挂上一个 so 就能跑。这份 4.1.1 最新版带了注册信息按第 2 章讲的方式调用 setKey 之后才会解锁完整的写入能力。它适合三类人后端服务里要定时出报表的、桌面客户端里要加导出功能的以及在工控机、设备端读写记录表的。2. 把 libxl 4.1.1 接进工程目录、链接参数与注册信息的落位二进制分发包最容易翻车的地方不是 API而是环境搭建。头文件放在哪个目录、链接时写-lxl还是-llibxl、运行时 so 找不到、注册信息在什么时候调用才生效——这四个问题会消耗掉大半的调试时间。所以先把工程接起来接对了再谈功能。2.1 包里给了什么先ls一遍再动手这类二进制分发包的结构基本是固定的先确认三样东西C 头文件目录、C 接口头文件目录、以及对应架构的 so 文件。常见做法是这样路径内容你需要确认的事include_cpp/libxl.hC 接口Book、Sheet、Format类文件里有没有namespace libxlinclude_c/libxl.hC 接口BookHandle、xlCreateXMLBook等与 C 头文件同名不要混着 includelib64/libxl.so64 位动态库file lib64/libxl.so看是不是 x86-64/aarch64lib/libxl.so32 位动态库和设备端架构对上才有用先用file命令确认 so 的架构。我在一台 aarch64 的工控板上遇到过目录名叫lib64、里面装的却是 x86-64 的库链接能过运行时才报错排查花了不少时间。确认完架构再确认你项目里 include 的是 C 还是 C 的那份头文件——两份同名头文件的路径不能同时加进-I否则编译器取到哪一份全看参数顺序属于典型的玄学问题。如果编译器是 g、但项目主体是 C直接#include libxl.h走 C 接口就行链接时记得补-lstdc因为 libxl 内部是 C 实现的纯 gcc 链接会缺符号。2.2 CMake 与手工链接两条路都走一遍现代一点的工程用 CMake关键是 include 目录、链接目录、rpath 三项都要写全尤其是 rpath——不写的话编译期没问题、跑起来就报“找不到 so”。cmake_minimum_required(VERSION 3.10) project(xls_report CXX) set(CMAKE_CXX_STANDARD 11) # 把解压后的 libxl 放在工程内的 third_party 下避免依赖绝对路径 set(LIBXL_ROOT ${CMAKE_SOURCE_DIR}/third_party/libxl) add_executable(xls_report main.cpp) # 1) 头文件目录只加 C 那份别和 C 接口目录混用 target_include_directories(xls_report PRIVATE ${LIBXL_ROOT}/include_cpp) # 2) 库目录 库名libxl.so 对应 -lxl target_link_directories(xls_report PRIVATE ${LIBXL_ROOT}/lib64) target_link_libraries(xls_report PRIVATE xl stdc) # 3) rpath编译期和安装后都能找到 so set_target_properties(xls_report PROPERTIES BUILD_RPATH ${LIBXL_ROOT}/lib64 INSTALL_RPATH $ORIGIN/../lib64)target_link_libraries里的xl是从libxl.so反推出来的写成libxl会变成找liblibxl.so。$ORIGIN表示可执行文件自身所在目录配合../lib64就能做成“整个目录拷到设备上直接跑”的绿色部署不用动系统库路径。如果你不用 CMake等价的手工命令是g -stdc11 main.cpp -o xls_report \ -Ithird_party/libxl/include_cpp \ -Lthird_party/libxl/lib64 \ -lxl -lstdc \ -Wl,-rpath,$ORIGIN/../lib64-Wl,-rpath,后面单引号不能省否则 shell 会把$ORIGIN当变量展开成空串编出来的程序还是找不到库。这一点在写 CI 脚本时特别容易忘本地测试正常、打包后崩属于“血泪经验”级别的细节。2.3 第一段能跑的代码建表、写格子、落盘接口上手成本很低Book是工作簿Sheet是工作表行列下标从 0 开始。写一个最小可运行版本#include libxl.h #include cstdio using namespace libxl; int main() { // xlsx 用 xlCreateXMLBook老式 xls 用 xlCreateBook Book* book xlCreateXMLBook(); if (!book) { printf(create book failed\n); return 1; } // 注册信息必须在 load/save 之前设置见 2.4 book-setKey(L注册名, L注册码); Sheet* sheet book-addSheet(L检测台账); if (!sheet) { book-release(); return 1; } // 表头加粗格式对象只建一次后面复用 Format* head book-addFormat(); head-setBold(true); head-setAlignH(ALIGNH_CENTER); sheet-writeStr(0, 0, L产线, head); sheet-writeStr(0, 1, L检测时间, head); sheet-writeStr(0, 2, L读数, head); // 数据行行列都是 0 基第 0 行被表头占了 sheet-writeStr(1, 0, LA线); sheet-writeNum(1, 1, 45123.5); // Excel 的日期序列值 sheet-writeNum(1, 2, 12.34); sheet-setColWidth(0, 10); // 列宽按字符宽度算 sheet-setColWidth(1, 20); if (!book-save(Ldemo.xlsx)) { printf(save failed\n); book-release(); return 2; } book-release(); // 必须调用否则内存和临时文件都不释放 printf(ok\n); return 0; }有两个点第一次用会踩writeStr的字符串是库内部拷贝一份你传临时对象也没事但readStr返回的指针归库所有不能free也不要跨release持有。另外addFormat()属于book而不是sheet同一个book下的所有 sheet 共用格式对象是正常用法跨 book 复用就是野指针。2.4 注册信息放哪setKey 的时机与凭据管理包里的注册信息对应setKey(name, key)两个参数调用时机很关键必须在任何load或save之前。放在xlCreateXMLBook()之后第一行最稳妥晚了就会出现“写出来的文件内容正常、但带着未授权标记”的情况很多人以为是库坏了其实只是顺序问题。凭据本身不建议硬编码在源码里。我一般的做法是走环境变量配置文件也行但别进版本库#include cstdlib #include libxl.h // 从环境变量取注册信息源码里不留明文 bool applyLicense(libxl::Book* book) { const char* name std::getenv(LIBXL_NAME); const char* key std::getenv(LIBXL_KEY); if (!name || !key) return false; // 缺凭据就明确失败别静默降级 // char* 转宽字符依赖当前 locale启动时先 setlocale(LC_ALL, ) wchar_t wname[128] {0}, wkey[512] {0}; mbstowcs(wname, name, 127); mbstowcs(wkey, key, 511); return book-setKey(wname, wkey); }setKey返回 bool建议把返回值打进日志出问题时一眼能看出是凭据没生效还是别的环节挂了。这段代码里mbstowcs的转换结果依赖 locale所以程序启动时要先setlocale(LC_ALL, )不然中文注册名会转成空串。提示这份包里的注册信息属于随包附带的授权凭据交付给客户或提交到公共仓库前先确认授权范围凭据泄漏和代码泄漏是两回事。3. 读写 Excel 的核心 API单元格类型、日期基准与 Format 对象接口接好之后真正决定“导出能不能用”的是三件事写进去的类型对不对、读出来的时候判没判类型、格式对象有没有复用。这三件事在 libxl 里都有明确的 API但默认行为不一定符合直觉。3.1 四种写入原语什么时候用哪个libxl 的写入口就四个选错会直接体现在结果文件里方法写入内容典型误用writeStr文本强制按字符串存把12.34当数字写下游求和全是 0writeNum双精度数字写日期忘了配NUMFORMAT_DATE显示成 45123writeBool布尔值用writeStr(true)Excel 里无法筛选writeFormula公式串不带等号带上前缀被当成文本原样显示writeFormula有个必须知道的行为libxl 只负责把公式写进去不会替 Excel 算出结果缓存值这一栏是空的。用 Excel 打开会自动重算但很多在线预览、服务端解析器、以及某些报表工具读的是缓存值就会显示 0 或空白。常见做法是公式和数值各写一份——公式放在隐藏列供人核对数值放在可见列给机器读或者导出后强制下游重算一次。// 公式不带等号同时把算好的值写到相邻单元格兼容不重算的读取方 sheet-writeFormula(2, 3, LSUM(D1:D2), nullptr); sheet-writeNum(2, 4, 24.68); // 与公式结果保持一致供机器读取3.2 读的时候先判类型别直接 readStr读表格最常见的写法是readStr一行行扫遇到空单元格返回 NULL遇到数字返回的是格式化后的字符串。问题在于日期、百分比、千分位这些格式会把原始值伪装起来你拿到的12.34%没法直接参与计算。稳妥的顺序是先判类型再决定用哪个读法。// 遍历时先看 cellType再决定用 readStr 还是 readNum for (int r 0; r sheet-lastRow(); r) { for (int c 0; c sheet-lastCol(); c) { CellType t sheet-cellType(r, c); if (t CELLTYPE_EMPTY || t CELLTYPE_BLANK) continue; if (t CELLTYPE_NUMBER) { if (sheet-isDate(r, c)) { // 日期格拿原始序列值再解包别用字符串 double d sheet-readNum(r, c); int y 0, m 0, day 0; book-dateUnpack(d, y, m, day); printf(%04d-%02d-%02d\n, y, m, day); } else { printf(%.4f\n, sheet-readNum(r, c)); } } else if (t CELLTYPE_STRING) { const wchar_t* s sheet-readStr(r, c); if (s) printf(%ls\n, s); // 指针归库所有不要 free } } }lastRow()和lastCol()返回的是“有内容的边界”不是整张表的行列数所以用它们做循环上界比硬编码安全。isDate必须和cellType CELLTYPE_NUMBER配合使用——日期在文件里本质就是个数字只有格式信息才能区分它到底是日期还是普通小数。3.3 日期为什么读出来是 450001900 基准与 datePackExcel 的日期是一个从 1900-01-00 起算的序列号45000大约对应 2023 年 3 月。所以直接readNum拿到日期格得到的一定是个四五万的小数小数部分就是时分秒。反过来写日期也一样writeNum写进去的只是一个数不配格式就永远不会显示成日期。// 写日期先打包成序列值再配日期格式 Format* dateFmt book-addFormat(); dateFmt-setNumFormat(NUMFORMAT_DATE); // 预定义常量够用就别自定义 double d book-datePack(2024, 3, 15, 8, 30, 0); // 年月日时分秒 sheet-writeNum(3, 1, d, dateFmt);datePack返回的序列值和 Excel 内部表示一致跨平台换算时区问题由你自己在上层处理——libxl 不做时区转换它只做序列值和年月日之间的算术。这一点在跨时区部署的服务上要特别注意同一份数据在东八区导出、在 UTC 机器上读回来日期可能差一天。常见做法是统一按业务时区打包读的时候也按同一时区解包中间不做本地时间转换。3.4 Format 对象数字格式、列宽与换行Format是控制“看起来怎么样”的唯一入口一次addFormat()拿到一个对象之后用 setter 逐项配置。常用的几项方法作用备注setNumFormat(...)数字/日期格式可用预定义常量也可传自定义格式串setAlignH/setAlignV水平/垂直对齐表头居中用得多setWrap(true)自动换行长文本列必开否则打印被截断setBold/setFont字体字体对象用book-addFont()单独建setBorder(...)边框报表类需求常用四边细线// 字体对象单独创建再挂到 Format 上两者都归 book 所有 Font* f book-addFont(); f-setName(L宋体); f-setSize(11); Format* cell book-addFormat(); cell-setFont(f); cell-setWrap(true); cell-setAlignV(ALIGNV_CENTER); cell-setNumFormat(L0.00); // 自定义两位小数自定义格式串的语法跟 Excel 的“设置单元格格式”完全一致0.00、#,##0、yyyy-mm-dd hh:mm都能直接传。列宽用setColWidth单位是字符宽度默认列宽大约 8.43超过 20 的中文列建议配合setWrap一起用。4. 批量导出与内存账4.1.1 在大表场景下的用法小表怎么写都行几千行以上就要开始算账了。libxl 的工作方式是整本加载进内存没有逐行流式写出这意味着内存占用跟表的大小是线性关系而且系数不小。这一章讲清楚开销在哪、怎么省。4.1 每格一个 Format 是最大的性能杀手新手写法容易在循环里book-addFormat()写一万行就建了一万个格式对象。这些对象在保存时要逐个序列化进 xlsx 的样式表文件体积可能翻好几倍保存耗时也从毫秒级涨到秒级。// 反例循环里创建格式对象 for (int r 1; r 10000; r) { Format* f book-addFormat(); // 一万个对象全部写进 styles.xml f-setNumFormat(L0.00); sheet-writeNum(r, 2, data[r], f); } // 正例格式对象在循环外建好循环内只传指针 Format* numFmt book-addFormat(); numFmt-setNumFormat(L0.00); for (int r 1; r 10000; r) { sheet-writeNum(r, 2, data[r], numFmt); }原理很简单xlsx 是一堆 XML 打包成的 zipxl/styles.xml里记录所有格式定义单元格只存一个索引。格式对象越少样式表越小序列化越快。我一般把格式收拢成一张“格式表”在初始化阶段一次性建好后面按枚举取用。4.2 内存占用估算与“分段落盘”的做法libxl 读 xlsx 时会把整本解析成内存对象树实际占用大概是文件体积的十几到二十几倍一个 20MB 的 xlsx峰值可能吃掉 400MB 以上如果只是读一个 sheet 里的几列这个代价就很难接受。没有流式接口的情况下实用的办法是“切分输入”按 sheet 拆成多个文件、按行数分成多个分片、或者让上游直接产出多个小文件再逐个处理。处理完一个release()一个不要在一个进程里同时持有两个Book。// 分片处理的骨架读一个、写一个、立刻释放 for (const auto part : parts) { // parts 是分片文件路径列表 Book* in xlCreateXMLBook(); in-setKey(name, key); if (!in-load(part.c_str())) { in-release(); continue; } Book* out xlCreateXMLBook(); out-setKey(name, key); Sheet* os out-addSheet(L汇总); // ……搬运并计算…… out-save(outPath.c_str()); out-release(); in-release(); // 关键下一个分片开始前释放 }这段骨架里release()的位置是重点。放在循环外内存会随分片数量单调增长放在save之后、下一个load之前峰值就稳定在单个分片的量级上。4.3 一个可复用的导出封装把上面这些收拢成一个类业务侧只需要填数据不用关心格式和释放class XlsWriter { public: XlsWriter(const wchar_t* name, const wchar_t* key) { book_ xlCreateXMLBook(); book_-setKey(name, key); sheet_ book_-addSheet(L数据); // 格式一次性建好全生命周期复用 fmtHeader_ book_-addFormat(); fmtHeader_-setBold(true); fmtHeader_-setAlignH(ALIGNH_CENTER); fmtNum_ book_-addFormat(); fmtNum_-setNumFormat(L0.00); } ~XlsWriter() { if (book_) book_-release(); } // RAII异常路径也释放 XlsWriter(const XlsWriter) delete; XlsWriter operator(const XlsWriter) delete; void header(int c, const wchar_t* text) { sheet_-writeStr(0, c, text, fmtHeader_); } void number(int r, int c, double v) { sheet_-writeNum(r, c, v, fmtNum_); } bool save(const wchar_t* path) { return book_-save(path); } private: Book* book_ nullptr; Sheet* sheet_ nullptr; Format* fmtHeader_ nullptr; Format* fmtNum_ nullptr; };析构里release()是必须的不只是为了内存——libxl 在保存 xlsx 时会用到临时资源不释放的进程在长期运行的守护服务里会缓慢泄漏。禁掉拷贝构造是为了防止两个对象持有同一个Book*那会直接导致二次释放崩溃。5. 五个高频翻车点从现象到原因到解法这些问题在邮件列表和代码托管平台的讨论里反复出现基本都是环境或语义理解偏差导致的不是库本身有 bug。5.1 中文列名变成问号或空串现象Windows 上编译运行正常代码原样拷到 Linux 上写出来的中文全是问号或者干脆是空字符串。原因wchar_t在两个平台上的宽度不一样Windows 是 2 字节UTF-16Linux 一般是 4 字节UTF-32。如果你的代码里用了wcslen、sizeof之类的操作去构造字符串或者手动做了宽窄字符转换跨平台就会错位。另外进程启动时没有setlocale宽字符输出到终端或转成路径时也会失效。解决统一用L字面量让编译器按当前平台的宽度生成跨平台层如果需要拼字符串用标准库的std::wstring而不是手工算长度程序入口加一行setlocale(LC_ALL, )中文文件名和中文输出才能正常。5.2 日期读回来是 45123.5 这种数字现象用readNum拿日期格得到的是一串四五万的数字直接当日期显示就成了天文数字。原因Excel 里日期就是数字加格式readNum拿的是原始序列值没有经过格式解释。isDate才是判断依据。解决读之前先if (sheet-isDate(r, c))再用dateUnpack拆成时分秒。写的时候反过来datePack打包成序列值再挂一个NUMFORMAT_DATE的格式对象两步缺一不可。5.3 公式写进去了打开显示 0 或者空白现象writeFormula之后用 Excel 打开没问题但换成在线预览、服务端解析库、或者某些报表工具读到的值是 0。原因libxl 只写公式文本不计算公式结果缓存值那一栏是空的。Excel 打开时会自动重算不重算的读取方就只能拿到空值。解决公式和结果同时写——公式放一列供人核对数值放另一列给机器读或者在下游导入时显式触发一次重算。对服务端解析场景建议直接写数值公式只在给人看的版本里保留。5.4 运行时报libxl.so: cannot open shared object file现象编译链接全部通过程序一启动就报找不到动态库用ldd看是not found。原因三种可能——rpath 没写或写错$ORIGIN被 shell 展开了so 的架构和可执行文件不匹配或者把库拷到了设备上但路径和编译时不一样。解决先用file确认架构一致再用ldd ./程序看它到底在找哪个路径临时验证用LD_LIBRARY_PATH./lib64 ./程序长期方案是把 rpath 写进编译参数。发布包里把 so 和可执行文件放成固定相对位置比依赖系统路径靠谱得多。5.5 保存返回失败或者文件存出来打不开现象save()返回 false或者返回 true 但生成的文件用 Excel 打开提示损坏。原因目标路径被占用文件正被 Excel 或 WPS 打开、目录没有写权限、中文文件名在非 UTF-8 locale 下转换失败、以及没有先setKey导致写出的文件不完整。解决先看save的返回值而不是假设成功接着确认目录权限和文件占用文件名尽量用 ASCII一定要用中文就把 locale 设成 UTF-8最后确认setKey在所有load/save之前。这四条按顺序查基本能覆盖九成问题。6. 五分钟自检确认手上的 4.1.1 是完整可用的一份拿到一个带注册信息的二进制库最怕的是“看着能用、关键功能缺一块”。我习惯先跑一个自检程序把中文、日期、公式、格式、合并单元格这五样全写一遍再用另一条技术路线读回来交叉验证——自己能读出来不算数别人能读出来才算。第一步用 2.3 那段代码改一版故意把这五个特性都塞进去// 自检用五类特性各写一处任何一项失败都能定位 sheet-writeStr(0, 0, L中文表头, fmtHeader_); // 1 中文 sheet-writeNum(1, 0, book-datePack(2024, 3, 15, 8, 30, 0), fmtDate_); // 2 日期 sheet-writeFormula(2, 0, LSUM(B1:B2), nullptr); // 3 公式 sheet-writeNum(3, 0, 1234.5678, fmtNum_); // 4 数字格式 sheet-mergeCells? // 5 合并单元格第二步别只用自己的库验证换成完全独立的一条链路读回来# 1) xlsx 本质是 zip先看结构完整不完整 unzip -l out.xlsx | grep -E sharedStrings|styles|sheet1 # 2) 抽出共享字符串表确认中文是 UTF-8 而不是问号 unzip -p out.xlsx xl/sharedStrings.xml | head -c 400 # 3) 用另一套技术栈读回来做字段级比对仅验证用不进生产 python3 - PY import openpyxl wb openpyxl.load_workbook(out.xlsx) ws wb.active print(repr(ws[A1].value), ws[A2].value, ws[A3].value, ws[A4].value) PY第三步把结果对到下面这张表上哪一行不符就回到对应章节查检查项期望结果不符时先怀疑中文表头读回来是完整中文不是?或空5.1 字符宽度与 locale日期格读回来是 2024-03-15不是 453665.2 少了 isDate 或格式对象公式缓存值不为空或下游能重算5.3 只写了公式没写值数字格式文件里显示两位小数setNumFormat传的是常量还是字符串合并单元格结构表里有mergeCell节点单元格写入顺序是否在合并之后这套自检我一般会在接入当天跑完顺手把输出文件用表格软件打开看一眼渲染效果——有些问题列宽挤压、换行被截断、边框缺失只有肉眼看得见靠解析器读不出来。从那以后我每接一个新的二进制库都会先花五分钟把这张表跑一遍再动手写业务代码省下的返工时间远超这五分钟。这份 4.1.1 带上注册信息按 2.4 的方式配好凭据上面五类特性都能一次过值得收进工具箱备用。希望帮到你。本文还有配套的精品资源点击获取