写 Excel 导出这件事，iOS 开发者迟早都会遇到。运营要一份用户数据、财务要月度报表、销售要客户台账，到了移动端就变成"能不能直接生成一个 .xlsx 发出去"。我最早用 CSV 糊弄过几次，后来发现根本不是那么回事，直到换到 libxlsxwriter 这个 C 库，才把 iOS 导出 Excel 的各种坑逐个填平。这篇文章把我从集成、API 实操到性能优化的完整经验写一遍，给准备在 iOS 上做表格导出的朋友做一个可复用的参考。

libxlsxwriter 是我目前用过最顺手的 iOS Excel 生成方案，核心价值在于：它是一个纯 C 库，直接生成符合 OpenXML 标准的 .xlsx 文件，不需要 App 端再装解释器或解析器，也不依赖网络请求服务端帮忙拼文件。你用 C 函数就能控制工作簿、工作表、单元格、样式、公式甚至图表，放到 iOS 工程里调用非常直接。如果你正在纠结用什么方案，或者被 CSV 的编码和多 Sheet 问题折磨过，这篇内容应该能帮上大忙。

1. 为什么说 iOS 导出 Excel 远比想象中麻烦

需求小而坑多，这是 iOS 做 Excel 导出的真实写照。很多业务一开始觉得"不就是把表格数据存成文件吗"，结果一细化需求就发现：要带表头颜色、要冻结首行、要有合计公式、要支持多 Sheet、要给负数标红。每一项都是在给方案选项加限制。

1.1 多数人踩过的两条弯路

第一条弯路是 CSV。CSV 确实简单，字符串拼一下、逗号一连接，写个文件就能发出去。但 CSV 本质是纯文本，根本没有单元格格式这一层。你没法给表头加背景色，没法设置数字格式，没法在一个文件里放多个工作表，也没法写公式让 Excel 自己算。更难受的是中文编码：Windows 上用 Excel 打开 UTF-8 的 CSV，经常是中文乱码，你转成 GBK 编码后数据是正常了，但有些 Mac 端的工具又显示成乱码。这种"换端就翻车"的体验，在真实用户手里非常掉价。

第二条弯路是用 HTML 表格伪装 Excel。有些人会把 HTML 写进 .xls 后缀的文件，靠浏览器兼容渲染出"像 Excel"的视图。这个方法在演示阶段确实能看，但发布出去之后问题一大把：很多邮件系统的附件预览直接判定文件格式无效，第三方库读取数据会拿到一堆 HTML 标签而不是干净的值，更别提无法做公式计算和数据透视。我后来总结出一个判断标准：只要数据要被程序再加工一次，HTML 伪装方案就绝对不能上生产。

1.2 原生导出能力盘点

iOS 系统本身没有提供"生成 .xlsx"的公共 API。UIKit 里的 UIDocumentInteractionController、QuickLook 都是用来预览已经存在的文件的，不负责生成新文件；CoreGraphics 倒是可以做 PDF 的绘制，但 PDF 是排版文档不是可编辑表格，完全两回事。所以现实情况就是：想在 iOS 上正经生成一个 Excel 文件，就得引入第三方库。

2. 方案选型：为什么 libxlsxwriter 能一站解决

选定 libxlsxwriter 之前，我认真对比过几个主流路径，这里也把当时的心路历程写出来，方便你判断自己需不需要换方案。

2.1 几个方案横评

我把备选方案和实际体验列成一张表，直接看差异：

CoreXLSX 是一个 Swift 库，读 xlsx 文件确实好用，但它的定位是解析而不是编辑生成。如果你要实现"读取再改动再另存"这种需求，写起来非常别扭，一些格式元素甚至没法保留。服务端生成方案虽然能利用成熟库，但存在两个硬伤：一是用户等结果依赖网络，弱网环境下体验很糟；二是数据如果量级大，上传下载都是成本。移动端本身就有完整的数据源，直接在本地生成文件反而是最合理的路径。

2.2 libxlsxwriter 的优势与核心特性

libxlsxwriter 的作者把它定位成"让 C 语言也能像脚本语言那样快速生成 Excel"。它做的核心事情非常硬核：在 C 层封装了 OpenXML 规范里的 xlsx 内部结构，单元格式、行高、列宽、公式、图表、图片、数据验证等能力应有尽有，全部转换成符合规范的 XML 和目录结构后打包成 zip，最终产出标准 .xlsx。

它的特性我用一句话概括：你能在 Excel 菜单里点出来的常用功能，API 基本都能覆盖。比如合并单元格、自动筛选、冻结窗格、条件格式、图表、数据透视表、单元格批注等。导出的是真正的 SpreadsheetML 标准文件，不是伪装格式，Excel、WPS、Mac 的 Numbers 都能正常打开。

调用方式上，由于它是个 C 库，iOS 端使用非常自然：不需要把数据桥接到某个动态语言运行时，直接在 C 函数里传指针就能完成所有操作。对 App 包大小的影响也很小，静态库加进去体积增加不多，在可接受范围内。

2.3 它不擅长的地方

任何工具都不是银弹。libxlsxwriter 只支持输出 .xlsx，不支持老式的 .xls 二进制格式。如果客户死咬住"非 .xls 不要"，这个方案就得放弃，不过现在基本都往 .xlsx 靠拢，影响不大。另外它是"生成文件"的工具，不是"读取文件"的解析器，如果你需要把已有的 Excel 文件读进 App 改一点再导出来，建议搭配 CoreXLSX 或系统自带的一些解析手段，而不是只依赖它。

3. 集成入库：iOS 交叉编译与工程配置

很多人在第一步就卡住了，因为 libxlsxwriter 官方推荐用 make/configure 构建，而 iOS 工程需要的却是一个包含模拟器架构和真机架构的静态库。这块我当时摸索过几条路，最稳定的两条是：脚本交叉编译和源码直编进工程。

3.1 编译一份全架构静态库

先说脚本交叉编译的思路。你需要先把源码 Clone 下来，然后用 Xcode 自带的工具链去 configure 和 make，分别产出 arm64 真机架构和 x86_64/arm64 模拟器架构的静态库，最后再用 lipo 合并。

我用的构建脚本大致是这个样子：

git clone https://github.com/jmcnamara/libxlsxwriter.git cd libxlsxwriter # 先编译真机 arm64 make clean ./configure --host=arm-apple-darwin --disable-shared \ CC="xcrun -sdk iphoneos clang" \ CFLAGS="-arch arm64 -isysroot $(xcrun -sdk iphoneos --show-sdk-path)" make cp src/libxlsxwriter.a ./libxlsxwriter-device.a # 再编译模拟器 make clean ./configure --host=x86_64-apple-darwin --disable-shared \ CC="xcrun -sdk iphonesimulator clang" \ CFLAGS="-arch x86_64 -isysroot $(xcrun -sdk iphonesimulator --show-sdk-path)" make cp src/libxlsxwriter.a ./libxlsxwriter-sim.a # 合并 lipo -create libxlsxwriter-device.a libxlsxwriter-sim.a \ -output libxlsxwriter-universal.a

注意一点：不同 Xcode 版本的参数会有些微变化，如果你的开发环境用的是 Xcode 15 之后的版本，模拟器还分 arm64 和 x86_64 两种 slice，那么模拟器部分要编译两次再合并。整个脚本我建议写成一个 build.sh 存进仓库，换电脑重装环境的时候一键执行，不用再手动折腾。

3.2 源码直编进工程

如果不想折腾交叉编译脚本，还有一条更朴素的路：直接把源码的 src 目录拖进 Xcode 工程，并添加头文件搜索路径。libxlsxwriter 的源码主体是 .c 文件，结构上很规整，没有太多依赖外部库的代码，往 Xcode target 里一拖，只要把 include 目录加到 Header Search Paths 里就能编。这种方式的好处是 Xcode 自动帮你处理架构差异，真机模拟器都能跑；坏处是工程里会多出一大堆源文件，看起来有点乱，且后续升级版本需要自己同步文件。

把工程配置这块做得尽量简单，我习惯在 Build Settings 里增加两项：

• HEADER_SEARCH_PATHS: 指向 libxlsxwriter 的 include 目录
• OTHER_LDFLAGS: 静态库版本加入-lz，因为 xlsx 打包依赖 zlib

如果编库时提示缺少头文件，先检查这两项，80% 的问题都能解决。

3.3 Swift 与 Objective-C 的调用姿势

如果你工程是 Objective-C，可以用workbook_new()这种 C 函数直接调。如果是 Swift，则需要在 Bridging Header 里引入xlsxwriter.h，否则编译器看不到 C 函数。引用写法在桥接头文件里加一行：

#include "xlsxwriter.h"

然后 Swift 代码里就能直接调了。写路径时注意，workbook_new 接收的是 C 字符串，不能直接传 NSString，Swift 里要调filePath.cString(using: .utf8)转一下。

4. 核心 API 实操：从创建文件到样式全面控制

走到这一步，你已经能把库编进工程了。现在聊聊怎么用它写出一份像模像样的 Excel。libxlsxwriter 的设计模型和 Excel 本身是高度对应的，工作簿、工作表、单元格、格式对象，一套概念全部保留，理解起来很顺畅。

4.1 最小可运行的写入流程

先看一个最简例子，它创建一个工作簿，往第一个工作表 A1 单元格写入字符串，然后关闭保存：

NSString *filePath = [NSTemporaryDirectory() stringByAppendingPathComponent:@"hello.xlsx"]; lxw_workbook *workbook = workbook_new([filePath UTF8String]); lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL); worksheet_write_string(worksheet, 0, 0, "Hello", NULL); lxw_error result = workbook_close(workbook); if (result == LXW_NO_ERROR) { NSLog(@"导出成功"); }

所谓的行和列在 API 里都是 0 基准的，worksheet_write_string(worksheet, 0, 0, ...)写的是第 1 行第 1 列，也就是 A1。这个写法和大多数表格库一致，记住这一点就不会被坐标搞晕。

workbook_close 会把所有数据打包写进文件，并释放内部资源。所以在业务代码里，这个函数是"收尾动作"，别调用两次，也别在没创建成功时调用。

4.2 write 系列函数：按数据类型挑选入口

写单元格内容不像你想象的那么神秘，libxlsxwriter 提供了一整套 write 系列函数，每个函数对应一种数据语义：

举个例子，如果明细数据里既有字符串又有数字，在循环里可以这么写：

for (NSInteger row = 1; row < rows.count + 1; row++) { NSDictionary *item = rows[row - 1]; worksheet_write_string(sheet, (lxw_row_t)row, 0, [item[@"name"] UTF8String], NULL); worksheet_write_number(sheet, (lxw_row_t)row, 1, [item[@"amount"] doubleValue], NULL); }

这里我建议你多写一步：在每行数据写入前，先看字段是否可能为 nil，尤其是从接口拿到的数据。一旦你给 C 函数传入一个 NULL 字符串，轻则字段缺失，重则崩溃。在导出模块里加一层"空值兜底"往往能省下不少排查时间。

4.3 格式全套：字体、边框、对齐、填充、数字格式

格式是 xlsx 相对 CSV 的最大优势，也是很多人想用又不熟悉的部分。libxlsxwriter 用一个 lxw_format 结构体承载所有样式描述，你可以通过一个又一个format_set_*函数去配置。

下面这段代码创建一个表头格式：加粗、白字、蓝底、居中、带边框。

lxw_format *headerFormat = workbook_add_format(workbook); format_set_bold(headerFormat); format_set_font_color(headerFormat, LXW_COLOR_WHITE); format_set_bg_color(headerFormat, LXW_COLOR_BLUE); format_set_align(headerFormat, LXW_ALIGN_CENTER); format_set_border(headerFormat, LXW_BORDER_THIN);

再把日期格式设置出来：

lxw_format *dateFormat = workbook_add_format(workbook); format_set_num_format(dateFormat, "yyyy-mm-dd");

这种格式对象本身并不绑定某个工作簿单元格，你可以反复复用它。一个经验是：把格式对象统一管理成属性或者常量，而不是在 for 循环里反复创建。因为格式对象数量过多时，xlsx 文件内部会冗余出大量 style 引用，文件体积变大不说，Windows 上 Excel 的加载速度也会明显变慢。

单元格对齐方向有两个：水平对齐用format_set_align，垂直对齐用format_set_vertical_align。数字格式的写法完全遵循 Excel 的格式串语法，比如#,##0.00显示千分位金额，0.0%显示百分比。

4.4 日期时间转换：绕不开的基础单元

Excel 里，日期本质是一个浮点数，从 1900-01-01 开始按天递增。libxlsxwriter 内部帮你完成从日期结构体到 Excel 日序号的转换，但它不知道你 App 里用的是 NSDate。你需要先把 NSDate 分解成年月日时分秒，填到一个lxw_datetime结构体里，再调用写入函数。

NSDateComponents *comps = [[NSCalendar currentCalendar] components:NSCalendarUnitYear | NSCalendarUnitMonth | NSCalendarUnitDay fromDate:someDate]; lxw_datetime dt; dt.year = (int)comps.year; dt.month = (int)comps.month; dt.day = (int)comps.day; dt.hour = 0; dt.min = 0; dt.sec = 0; worksheet_write_datetime(worksheet, row, col, &dt, dateFormat);

如果你看到单元格里显示出一串 42005 之类的数字，不用怀疑，就是没给这一列指定日期格式导致的。要么在表头格式里设置数字格式，要么单独给该列所有单元格绑定一个带yyyy-mm-dd格式的格式对象。

4.5 合并单元格、列宽与自动列宽估算

合并单元格是 Excel 报表里几乎一定会用到的功能，比如大标题跨多列。API 长这样：

worksheet_merge_range(worksheet, 0, 0, 0, 4, "2024年6月进销存汇总", titleFormat);

参数分别表示首行、首列、末行、末列和内容，区域范围内合并成一个单元格。

列宽设置也需要单独处理。xlsx 的列宽单位约等于一个英文字符的宽度，中文字符的显示宽度差不多是英文的两倍，所以"自动列宽"官方并不提供，需要自己在代码里估算。我这边的做法是先遍历整列数据的字符串长度，按中文计 2、英文计 1 累加，最后给一个余量值，防表头和文字被截断：

- (double)estimatedColumnWidthForValues:(NSArray<NSString *> *)values { double maxWidth = 5; for (NSString *value in values) { double width = 0; for (NSInteger i = 0; i < value.length; i++) { unichar c = [value characterAtIndex:i]; if (c >= 0x4E00 && c <= 0x9FFF) { width += 2; // 中文字符更宽 } else { width += 1; } } if (width > maxWidth) { maxWidth = width; } } return maxWidth + 2; }

再用 worksheet_set_column 写入列宽：

worksheet_set_column(sheet, 0, 0, [self estimatedColumnWidthForValues:col0Values], NULL);

如果忘了设置列宽，默认列宽大约是 8.43 个字符，遇到客户名称或者备注这种动辄十几个字符的内容，导出的表格基本没法看。

5. 实战：月度进销存报表导出

前面的基础打好了，我们来做一个带业务语义的完整案例。假设某贸易公司需要导出一份月度进销存 Excel，表格结构是：第一行大标题，第二行表头，接下来是每个货品的库存明细，最后一行是合计公式，还要求冻结表头行、筛选表头列。这个场景覆盖了样式、公式、结构优化三个方面，非常适合当范例。

5.1 数据模型与模板设计

先把 Excel 模板在脑海里定义出来：

• A 列：日期
• B 列：货品名称
• C 列：入库数量
• D 列：出库数量
• E 列：结存数量
• F 列：备注

最后一行合计，C 列统计入库总数，D 列统计出库总数。模板设计阶段就把"用户要什么、谁在哪个位置"定好，写代码时才会像填空一样顺畅。

5.2 创建表头、标题与汇总行样式

代码里先定义几个复用格式：标题格式、表头格式、数据格式、汇总格式、负值红色格式。

lxw_format *titleFormat = workbook_add_format(workbook); format_set_bold(titleFormat); format_set_font_size(titleFormat, 16); format_set_align(titleFormat, LXW_ALIGN_CENTER); format_set_border(titleFormat, LXW_BORDER_THIN); lxw_format *headerFormat = workbook_add_format(workbook); format_set_bold(headerFormat); format_set_font_color(headerFormat, LXW_COLOR_WHITE); format_set_bg_color(headerFormat, 0x4472C4); format_set_align(headerFormat, LXW_ALIGN_CENTER); format_set_border(headerFormat, LXW_BORDER_THIN); lxw_format *redFormat = workbook_add_format(workbook); format_set_font_color(redFormat, LXW_COLOR_RED); format_set_border(redFormat, LXW_BORDER_THIN);

这样标题有标题的样子，表头有表头的配色，看到数据是负数时还可以用红色强调，业务人员在手机上一眼就能发现问题。

5.3 写入明细、汇总公式与负值标红

写入部分遵循前面的行模型，循环处理明细：

NSInteger dataStartRow = 2; // 第3行开始写数据 NSInteger dataEndRow = dataStartRow + self.items.count - 1; for (NSInteger i = 0; i < self.items.count; i++) { NSInteger row = dataStartRow + i; InventoryItem *item = self.items[i]; worksheet_write_datetime(ws, row, 0, &dt, dateFormat); worksheet_write_string(ws, row, 1, [item.name UTF8String], cellFormat); worksheet_write_number(ws, row, 2, item.inboundQty, cellFormat); worksheet_write_number(ws, row, 3, item.outboundQty, cellFormat); worksheet_write_number(ws, row, 4, item.stockQty, item.stockQty >= 0 ? cellFormat : redFormat); worksheet_write_string(ws, row, 5, [item.remark UTF8String], cellFormat); }

最后写入合计行，用公式汇总 C 列和 D 列的整列数据：

NSInteger totalRow = dataEndRow + 1; char formula[256]; snprintf(formula, sizeof(formula), "=SUM(C%d:C%d)", (int)dataStartRow + 1, (int)dataEndRow + 1); worksheet_write_formula(ws, totalRow, 2, formula, sumFormat); snprintf(formula, sizeof(formula), "=SUM(D%d:D%d)", (int)dataStartRow + 1, (int)dataEndRow + 1); worksheet_write_formula(ws, totalRow, 3, formula, sumFormat);

这里有个细节：行坐标在 API 里是 0 基准，但公式字符串里的行号Excel 用的是 1 基准，所以从 NSInteger 行号转成公式里的行号需要 +1。这个 0 基准和 1 基准的混用是新手最常犯的错误，写出来的公式一打开就是错误的引用区域，我踩过这个坑，印象特别深。

5.4 冻结首行、自动筛选与页面布局

表头和标题有了，数据也有了，最后做结构和体验层面的优化。冻结窗格用于让用户滚动数据时始终可以看到表头，用 freeze_panes 实现：

worksheet_freeze_panes(ws, 2, 0);

这个调用的含义是冻结前两行，滚动时表头始终固定在上方。如果你要同时冻结首列，第二个参数传 1 就行。

自动筛选是另一个提升查阅体验的功能：

worksheet_autofilter(ws, 1, 0, (lxw_row_t)totalRow, 5);

参数依次是筛选区域的起始行、起始列、结束行、结束列，筛选条件会覆盖表头和数据区，用户在下拉框直接过滤想要的数据。这里注意筛选区域的第一行要对应表头行，别从标题行开始。

页面布局方面，如果导出的是需要打印的报表，最好设置一下页面方向：

worksheet_set_landscape(ws);

这样一个横过来的 Excel 打印出来比较符合报表阅读习惯。

5.5 写入文件并调起系统分享

文件保存路径一般放在临时目录，或者 App 的 Documents 目录。Documents 适合需要用户长期保留的场景，临时的分享则用 NSTemporaryDirectory，iOS 系统会自动清理。

NSString *tmpPath = NSTemporaryDirectory(); NSString *fileName = @"库存报表_202406.xlsx"; NSString *filePath = [tmpPath stringByAppendingPathComponent:fileName]; lxw_workbook *workbook = workbook_new([filePath UTF8String]); // ... 所有写入逻辑 ... workbook_close(workbook);

生成之后调起系统分享：

NSURL *fileURL = [NSURL fileURLWithPath:filePath]; UIActivityViewController *activityVC = [[UIActivityViewController alloc] initWithActivityItems:@[fileURL] applicationActivities:nil]; activityVC.popoverPresentationController.sourceView = self.view; [self presentViewController:activityVC animated:YES completion:nil];

实际分享时我遇到过一个问题：用户通过微信接收 xlsx 后，微信内置预览偶尔会提示文件格式不支持。这不是你导出的文件有问题，而是微信的预览组件对 xlsx 的支持比较弱。可以在分享文案里引导一句"请使用 Excel 或 WPS 打开"，或者给业务方额外提供一个 PDF 版本作为补充，体验会好很多。

6. 常见问题排查与性能经验

文档里写得再顺畅，落地时总会遇到一些奇怪状况。我把这些年在导出 Excel 过程中遇到的典型问题整理成表，这也是我认为这篇文章里最有价值的部分。

6.1 高频问题速查表

6.2 大量数据导出时怎么保住内存

如果你要导出上万行甚至十几万行的明细数据，默认内存模式下库会在内存里缓存全部单元格数据，然后等 workbook_close 时一次性写入。这个设计在普通报表上没问题，数据量大时很容易触发内存警告。

解决办法是用常量内存模式。开启后，数据按行写入后立即落盘，避免全部驻留内存，代价是写入顺序必须严格从第 0 行开始逐行递增，不能再往前跳到某个旧行随意写。

lxw_workbook *workbook = workbook_new([filePath UTF8String]); workbook_set_constant_memory(workbook, LXW_TRUE);

如果业务报表数据超过两万行，我强烈建议直接开这个模式。同时你别在 Excel 里塞太多图片，图片资源本身也会大量占用内存。

6.3 中文字体、乱码与多端兼容

乱码问题多数上出现在两个环节：拼接路径时、写入字符串时。在 iOS 里，NSString 到 C 函数必须走UTF8String，在 Swift 里则是filePath.cString(using: .utf8)。还要保证你的 xlsx 内部字体能正确渲染中文，libxlsxwriter 默认字体在某些系统打开时可能会出现中文宽度异常的情况，建议给正文格式指定一个系统通用中文字体名。

在 iOS 上我常用PingFang SC，设置方式：

format_set_font_name(bodyFormat, "PingFang SC");

导出文件在 Windows、Mac、WPS 三端都打开验证过，基本没有兼容性问题。如果客户经常用 WPS 打开，尽量别用过于特殊的字体名，比如某个只在苹果系统存在的字体，别人打开时回退成默认字体反而影响排版。

6.4 App Store 审核相关注意点

libxlsxwriter 本身是一个纯 C 实现的开源库，不调用私有 API，没有网络请求，也不会在运行时动态加载代码，因此过审风险很低。唯一要留意的点在于开源许可要求：库基于宽松的 BSD 协议，使用它基本没有合规压力，但产品上线时最好在"第三方开源组件"页面里带上版权声明，养成习惯总没有坏处。

另外还有一个容易被忽略的审查点：如果导出功能是在本地完成，不需要申请任何特殊权限；一旦你为了分享文件调用了 UIActivityViewController，就只涉及文件访问权限，不需要在 Info.plist 里额外声明。保持导出的业务逻辑在本地闭环，审核材料也会更简单。

7. 最后想说的几句真心话

我在实际项目里用 libxlsxwriter 导出的文件量已经很可观了，最大的感受是：选对库只是第一步，真正拉开差距的是你对 Excel 使用习惯的理解深度。你越能用 Excel 原生的语义去设计报表，用户就越觉得这个导出功能"专业"。比如表头冻结、自动筛选、负数标红、合计公式，这些功能单独写都不难，组合在一起，用户的体感会有质的提升。

最后分享一个小技巧：在你交付导出功能之前，把生成的 xlsx 文件用三种不同的表格软件各打开一遍。WPS、Microsoft Excel、Mac Numbers 对个别细节的处理并不完全一致，哪怕标准一致，某些边缘样式的渲染也有差异。提前做一次多端冒烟测试，比上线后被用户截图反馈"排版乱了"要划算得多。