企业官网建设流程全解析

Apache POI 在 Java 生态里做 Excel 导出导入，属于绕不开的老牌技术选型了。尤其 XSSFWorkbook，可以说承载了绝大多数 .xlsx 格式读写需求。我这些年碰到不少同事一上来就new XSSFWorkbook()往内存里塞几万行数据，结果 OOM 直接教做人——这不是 POI 不行，而是没搞明白它的内存模型就急着下手了。

这篇就围绕 XSSFWorkbook 的原理和实践展开，我尽量把底层的设计逻辑、日常操作的高频 API、以及大数据量场景下的替代方案都讲透。文中涉及的代码都可以直接拿去改改用，你如果正在用 POI 处理 Excel，或者准备做 Java 导出报表功能，这篇文章应该能帮你少踩不少坑。

1. 内容整体设计与思路拆解

1.1 XSSFWorkbook 到底是什么

先说名字的由来。POI 项目里操作 Excel 2003 及以前版本的.xls文件用 HSSF（Horrible Spreadsheet Format），而XSSFWorkbook对应的是 Excel 2007+ 的.xlsx格式，底层基于 OOXML（Office Open XML）标准。简单理解，.xlsx本质上是一个 ZIP 压缩包，里面装着若干 XML 片段：sheet1.xml存单元格数据，styles.xml存样式定义，sharedStrings.xml存共享字符串，workbook.xml描述工作表结构。

XSSFWorkbook 做的事情，就是把这些 XML 片段映射成 Java 对象树。你调用createRow()、createCell()、setCellValue()时，实际上是在内存里构建一棵 DOM 树。等你调用workbook.write(outputStream)时，POI 再把内存中的这棵树序列化回 XML，压缩成.xlsx。这也是它跟 EasyExcel、FastExcel 这类新型框架最大的区别所在——它是一次性把整份文档读进内存操作，典型的内存换速度策略。

1.2 为什么会有内存溢出问题

热词里不少人搜“XSSFWorkbook 内存溢出”，这基本都踩在同一个坑上：XSSFWorkbook 在默认参数下，会把整张表的所有行、所有单元格、所有样式、所有字符串全部保留在 JVM 堆内存里。即使你只填了 100 列，每列一个字符串，10 万行就是 1000 万个单元格对象。每个XSSFCell内部还挂着自己的CellStyle引用、字体对象、超链接、注释等附属结构，内存占用呈几何级数膨胀。

我实测过一个不算夸张的场景：用 XSSFWorkbook 写 20 万行、每行 20 列纯字符串数据，JVM 堆开了 1GB，跑完直接java.lang.OutOfMemoryError: Java heap space。这不是代码写得有问题，而是 XSSFWorkbook 的设计边界就在那里。了解它的原理不是为了绕开它，而是让你知道什么时候该用它、什么时候必须换方案。

1.3 什么时候选 XSSFWorkbook，什么时候换 SXSSFWorkbook

按我的实践经验，可以画一条粗略的分界线来选型：

当然，XSSFWorkbook 还有一个优势是 SXSSF 无法替代的：它支持读取后再修改，并且可以访问任意行、任意单元格的完整信息。SXSSF 只支持写入，不支持读取，也没有随机访问能力。所以如果你要做的是“模板导出、填数据、加公式”这类操作，XSSFWorkbook 依然是首选。

2. 核心 API 拆解与实操要点

2.1 工作簿、工作表与单元格的基本操作

我直接写一段最小可用的示例，这个结构你会频繁用到：

import org.apache.poi.xssf.usermodel.XSSFWorkbook; import org.apache.poi.ss.usermodel.*; try (Workbook workbook = new XSSFWorkbook()) { Sheet sheet = workbook.createSheet("销售报表"); // 创建表头行 Row headerRow = sheet.createRow(0); String[] headers = {"日期", "产品", "销量", "金额"}; for (int i = 0; i < headers.length; i++) { Cell cell = headerRow.createCell(i); cell.setCellValue(headers[i]); } // 写入数据行 for (int r = 1; r <= 100; r++) { Row row = sheet.createRow(r); row.createCell(0).setCellValue("2024-01-" + String.format("%02d", (r % 28 + 1))); row.createCell(1).setCellValue("产品" + r); row.createCell(2).setCellValue(r * 10); row.createCell(3).setCellValue(r * 10 * 9.9); } // 调整列宽，让数据不至于挤在一起 for (int i = 0; i < headers.length; i++) { sheet.autoSizeColumn(i); } try (FileOutputStream fos = new FileOutputStream("report.xlsx")) { workbook.write(fos); } }

几个关键点说一下。workbook.write(fos)内部会先 flush 所有缓冲数据，再关闭底层资源，所以外层建议用 try-with-resources 管理Workbook和输出流。autoSizeColumn虽然方便，但它会遍历列内所有单元格来计算宽度，数据量大时性能很差，我一般只在列数少、行数少的时候用，否则宁可手动设置固定列宽。

这里有个容易踩的坑：很多人以为createSheet不传参数会默认生成“Sheet1”，实际上 POI 的默认逻辑会生成名为 "Sheet0" 的工作表。如果后续代码依赖工作表名称查找（比如workbook.getSheet("Sheet1")），就会返回 null。我的习惯是显式指定工作表名称。

2.2 样式与格式化的底层逻辑

Excel 的样式体系在 POI 里是“池化”的——样式对象不是每个单元格各自持有，而是统一挂在 workbook 级别的样式表里。单元格只存一个索引，指向样式表中的某个CellStyle。这种设计大大缩减了内存和文件体积，但反过来意味着：如果你每创建一个单元格都createCellStyle()一次，样式表会爆炸式膨胀。

我见过真实案例：某报表逻辑在循环里createCellStyle，只导了 5 万行数据，生成的 xlsx 文件从正常的 200KB 膨胀到 20MB，打开还卡顿。原因就是生成了几万个冗余样式对象。正确做法是把样式提出来复用，放在循环外部：

CellStyle highlightStyle = workbook.createCellStyle(); Font font = workbook.createFont(); font.setBold(true); font.setColor(IndexedColors.RED.getIndex()); highlightStyle.setFont(font); highlightStyle.setFillForegroundColor(IndexedColors.YELLOW.getIndex()); highlightStyle.setFillPattern(FillPatternType.SOLID_FOREGROUND); // 然后在循环里复用 cell.setCellStyle(highlightStyle);

这里还有个隐藏上限需要你知道：.xlsx格式的样式数量上限是 65,490（styles.xml中最多 65,490 个单元格格式记录）。正常情况下不会触达这个限制，但如果你在循环里不断createCellStyle()，几万次循环后就会触发IllegalStateException: The maximum number of cell styles was exceeded。这个报错不像 OOM 那么直观，很多人排查半天也想不到是样式对象创建太多导致的。

日期格式也是一个高频需求点。POI 里设置日期格式需要两步：先给单元格放进一个java.util.Date对象，再给它配上DataFormat：

CellStyle dateStyle = workbook.createCellStyle(); dateStyle.setDataFormat(workbook.getCreationHelper().createDataFormat().getFormat("yyyy-MM-dd HH:mm:ss")); Cell cell = row.createCell(0); cell.setCellValue(new Date()); cell.setCellStyle(dateStyle);

如果只setCellValue(new Date())而不配日期格式，你看到的将是 Excel 默认的天数序列值，比如 45292.34567，对用户毫无可读性。

2.3 合并单元格与公式计算的细节

合并单元格的 API 一眼看上去很简单：

sheet.addMergedRegion(new CellRangeAddress(0, 2, 0, 0)); // 合并从第1行到第3行、第1列

但注意几个容易被忽略的规则。合并后的区域只有左上角单元格有值，其余单元格是空的。如果你先给区域内的所有单元格都赋了值，再合并，那么只有左上角的值被保留，其他值会丢失。而且合并区域的边框样式需要手动设置到每个边界单元格，POI 不会自动处理。我在做报表时经常要先把整个表格区域设好边框样式，再执行合并，否则合并区域的边框会缺漏，看起来很粗糙。

公式计算这块，POI 有一条跟 Excel 不太一样的规则：XSSFWorkbook 默认不开启公式自动重算。你往Cell里写入setCellFormula("SUM(C1:C10)")后，用 POI 读取这个公式的计算结果时，拿到的往往是0或者上一次打开文件时 Excel 计算好的缓存值，而不是新的计算值。如果需要让 POI 帮你计算，必须手动触发：

workbook.setForceFormulaRecalculation(true); // 或者显式求值 FormulaEvaluator evaluator = workbook.getCreationHelper().createFormulaEvaluator(); CellValue value = evaluator.evaluate(cell); double result = value.getNumberValue();

这里提醒一句：setForceFormulaRecalculation(true)只是往 workbook 里写入一个“下次打开时需要重算”的标记，在 Excel 打开文件时生效，POI 自身的读取依然不会自动计算。如果你要在程序里拿到公式结果，只能显式走FormulaEvaluator。这是很多从 Apache POI 入门到放弃的人的经典困惑点。

3. 实操过程与核心环节实现

3.1 大数据量写入：内存监控与分批策略

前面说了，XSSFWorkbook 不适合海量数据写入。但如果你手头项目用了旧版本 POI，或者说你进入的是一个已经大量依赖 XSSFWorkbook 代码的存量项目，有几种方法可以在不大改代码的情况下减轻内存压力。

先说最直接的：分批写入并释放引用。比如你有 50 万行数据需要导出，可以考虑拆成多个文件分别生成，最后再合并。这个方法听起来粗暴，但实际上很管用。我还见过更细的优化方案——用XSSFWorkbook的dispose()方法（POI 3.17+ 提供）显式释放内存中的底层 XML 资源。在写完整份文档并关闭工作簿之前调用dispose()，确实能释放一部分包结构的内存结构。

不过说实话，我多次实测下来，这些方法治标不治本。XSSFWorkbook 的瓶颈在于数据模型本身，而不是对象生命周期管理。你在循环里写 100 万行，JVM 堆里的对象引用不是你立刻dispose就能回收的，GC 压力依然巨大。

真正该做的是：数据量超过 10 万行时切到 SXSSFWorkbook。它内部维护一个滑动窗口，默认窗口大小是 100 行——也就是说它只保留最近 100 行在内存中，更早的行已经写入临时文件并释放了引用。底层它用的是XSSFWorkbook的XSSFSheet数据对象，但通过包装实现流式输出。

import org.apache.poi.xssf.streaming.SXSSFWorkbook; try (SXSSFWorkbook workbook = new SXSSFWorkbook()) { // 可选：调整窗口大小 // SXSSFWorkbook workbook = new SXSSFWorkbook(500); Sheet sheet = workbook.createSheet("大数据导出"); for (int r = 0; r < 200000; r++) { Row row = sheet.createRow(r); row.createCell(0).setCellValue(r + 1); row.createCell(1).setCellValue("数据行" + r); row.createCell(2).setCellValue(Math.random() * 10000); } try (FileOutputStream fos = new FileOutputStream("big_export.xlsx")) { workbook.write(fos); } // 重要：让 SXSSFWorkbook 删除临时文件 workbook.dispose(); }

注意 SXSSFWorkbook 必须手动调用dispose()，它会清理落盘的临时文件。如果漏掉，临时文件会残留在系统临时目录里，日积月累是个隐患。另外setCellValue写入的是实时数据，SXSSF 不会像 XSSF 那样支持事后修改已经刷出窗口的行。这也意味着，如果你需要在写完一批数据后回头修改某一行，就必须在窗口内完成。

我做大数据量导出的标准模板是：

1. 确认数据源总量级（通过SELECT COUNT(*)或接口返回的 total）
2. 超过 10 万行走 SXSSFWorkbook 分批查询、分批写入
3. 每批数据 5000 行，写完后Row和Cell引用不再保留
4. 输出到文件时先写缓冲流BufferedOutputStream，避免网络 IO 或磁盘 IO 成为瓶颈

3.2 大数据量读取：EventModel 与流式解析思路

写可以换 SXSSFWorkbook，读就没有这么轻松了。XSSFWorkbook在读取文件时同样会把整张表恢复到内存中，如果服务端要解析一个 50MB 的 Excel，内存直接吃紧。此时 POI 官方推荐的是使用XSSFReader，也就是基于 SAX 的事件驱动解析。

关于XSSFReader的细节我不铺开讲代码了，但思路值得告诉每个人：.xlsx是一个 ZIP 包，你可以解开这个包取出xl/worksheets/sheet1.xml，然后基于XMLReader解析sheetData节点中的行和单元格事件。这样你一次只处理一行数据，读完一行就可以丢进业务层持久化，内存占用跟文件里的数据总量几乎无关。

如果你不想纯手写 SAX，POI 也为XSSFSheetXMLHandler提供了辅助类，可以直接把单元格事件转发给SheetContentsHandler接口。你自己实现这个接口就能拿到cell(String cellReference, String formattedValue, XSSFComment comment)回调。这是 POI 官方示例里处理大 Excel 的标准姿势。

我贴一个基于XSSFSheetXMLHandler读取大批量文件的骨架，这在面试里也经常被问到：

import org.apache.poi.xssf.eventusermodel.XSSFSheetXMLHandler; import org.apache.poi.xssf.eventusermodel.XSSFReader; import org.apache.poi.xssf.model.StylesTable; import org.apache.poi.openxml4j.opc.OPCPackage; try (OPCPackage pkg = OPCPackage.open("big_file.xlsx")) { XSSFReader reader = new XSSFReader(pkg); StylesTable styles = reader.getStylesTable(); XSSFReader.SheetIterator sheets = (XSSFReader.SheetIterator) reader.getSheetsData(); while (sheets.hasNext()) { try (InputStream sheetStream = sheets.next()) { InputSource source = new InputSource(sheetStream); XSSFSheetXMLHandler handler = new XSSFSheetXMLHandler( styles, null, new MySheetContentsHandler(), false ); XMLReader parser = XMLHelper.newXMLReader(); parser.setContentHandler(handler); parser.parse(source); } } }

这里MySheetContentsHandler自己实现SheetContentsHandler接口即可，在cell()方法里逐单元格处理数据，或者在endRow()里把整行收集齐再写库。样式表StylesTable必须在循环外获取一次，因为sheet1.xml本身不携带样式定义，样式都是索引引用。

此时的坑在于“数据类型判断”。SAX 事件流中，POI 给你的可能是格式化后的字符串（比如日期被格式化成了2024/01/15），也可能是原始值（数字）。如果你要做日期转换或精确数值计算，不能直接拿formattedValue字符串去 parse，而是应该通过cellReference和单元格类型去定位。这个细节在做数据导入时尤其折磨人，我曾经因为直接把数字列formattedValue拿到Float.parseFloat上，结果遇到 Excel 里显示为“科学计数法”的数字，直接解析失败。

3.3 模板填充实战：保留样式与公式

回到 XSSFWorkbook 最典型的使用场景：根据 Excel 模板填充数据。运维报表、财务月报、成绩单，这类需求几乎都是先做好模板，再由 Java 后台填充数据。这里有个关键点：用XSSFWorkbook打开模板文件时，模板中已有的样式、合并单元格、公式、数据验证都会被完整保留，你只需要定位到目标单元格填入数据即可。

模板填充我有几个固定写法：

try (Workbook workbook = new XSSFWorkbook(new FileInputStream("template.xlsx"))) { Sheet sheet = workbook.getSheet("数据页"); // 定位到第 2 行第 1 列（假设模板第一行是标题，第二行开始是数据） Row row = sheet.getRow(1); if (row == null) { row = sheet.createRow(1); } Cell cell = row.getCell(1); if (cell == null) { cell = row.createCell(1); } cell.setCellValue("实际填入内容"); // 保持原模板的单元格样式—— // 注意 getCell(1) 如果返回 null，此时样式会丢失，需要手动从相邻单元格复制样式 CellStyle templateStyle = sheet.getRow(1).getCell(0).getCellStyle(); cell.setCellStyle(templateStyle); try (FileOutputStream fos = new FileOutputStream("filled_template.xlsx")) { workbook.write(fos); } }

这里有一个非常容易踩的坑：row.getCell(n)返回的可能是 null，如果模板的某些单元格是空白的，程序不会自动帮你在那个位置“恢复并复制样式”。我的处理方式是写一个小工具方法：getOrCreateCellByStyleTemplate(targetRow, colIndex, styleSourceCell)，先判断单元格是否存在，不存在就创建并复制相邻单元格的样式。这样能保证模板整体观感一致，不出现“有的单元格有边框，有的没有”的尴尬。

3.4 写入性能对比与优化参数

这里分享一组我自己做过的小实验数据，环境是 POI 5.2.3、JDK 8、默认 JVM 参数，写 50 行 x 10 列、5 万行 x 10 列各一次。数据类型包含字符串、数字、日期。

这组数据仅供参考，但结论很明显：数据量一旦上一个量级，XSSFWorkbook 的内存瓶颈会直接抹平它在 API 易用性上的优势。所以你在设计导出功能时，最优先的问题是：这个功能的上限是多少行。写死这个上限，再决定用 XSSFWorkbook 还是 SXSSFWorkbook。

如果因为业务特殊原因必须用 XSSFWorkbook 处理较大数据，可以通过 JVM 启动参数临时提堆：-Xmx4g -Xms1g。但我不推荐把这当常规方案——堆大不代表 GC 压力小，反而会带来更长的停顿。

4. 常见问题与排查技巧实录

4.1 内存溢出：OOM 之后怎么定位

遇到java.lang.OutOfMemoryError: Java heap space，先不要急着加堆参数。我建议按这个顺序排查：

1. 看导出行数——如果超过 10 万行，直接用 SXSSFWorkbook 替换 XSSFWorkbook，别挣扎。
2. 看循环里有没有创建大量样式对象、字体对象、图片对象。这些对象虽然体积小，但数量大了就是内存黑洞。
3. 看是否用了autoSizeColumn。每列调一次相当于遍历整列，行数多时 CPU 和内存双高。
4. 如果确认是 XSSFWorkbook 的 DOM 树过大，考虑用XSSFWorkbook.dispose()或者换流式方案。

还有一个隐蔽点：new XSSFWorkbook(InputStream)时，POI 会尝试把整个输入流读入内存再解析 ZIP 结构，而不是直接流式读取。所以如果你从网络接口拿 Excel 流并直接传入new XSSFWorkbook(inputStream)，内存会多出一份完整的流副本。建议先落盘成临时文件，再用OPCPackage.open(File)的方式读取。这个细节在读取大文件时提升明显。

4.2 公式不生效、日期变数字、中文变问号

这三个问题分别有不同的原因和解法，我列个速查表，你在实战中可以直接对照。

4.3 XSSFWorkbook 并发写入的边界

这一点很多人没注意：XSSFWorkbook 对象是非线程安全的。如果你在多个线程里同时操作同一个 workbook 实例，会出现各种并发修改异常，最典型的是ConcurrentModificationException和NullPointerException出现在深层 POI 类里，很难排查。

所以遇到并发导出需求，我的做法是“线程内独立 Workbook”。每个请求线程创建自己的 XSSFWorkbook，互不干扰，写完关闭。如果你追求的是多线程写入同一个 Excel 的不同 Sheet，这在 POI 里几乎不可行，因为 Workbook 内部的各种 Map、List 容器没有加锁。实在要合并多个线程导出的数据，就先让每个线程独立生成一个临时文件，最后再用XSSFWorkbook做一次合并拷贝。

合并拷贝的方式很简单：

try (Workbook merged = new XSSFWorkbook()) { for (File part : partFiles) { try (Workbook partWorkbook = new XSSFWorkbook(new FileInputStream(part))) { Sheet srcSheet = partWorkbook.getSheetAt(0); Sheet destSheet = merged.createSheet(srcSheet.getSheetName()); copySheet(merged, srcSheet, destSheet); } } }

copySheet的通用实现网上很多，本质就是从源 sheet 遍历行列单元格，逐一复制值和样式。注意复制CellStyle时不能直接setCellStyle(srcCell.getCellStyle())，因为样式对象是挂在各自 workbook 上的，必须用merged.createCellStyle()创建一个新样式并复制属性。我吃过这个亏，跨 workbook 复用样式对象会导致端到端格式错乱。

4.4 老版本 API 与新版本的兼容坑

如果你项目里用的还是 4.x 甚至 3.x 的 POI，有几个 API 迁移需要注意。POI 从 4.0 开始把org.apache.poi.ss.usermodel包名下的类作为统一入口，旧代码经常混用HSSFWorkbook和XSSFWorkbook的逻辑。在新版本中，WorkbookFactory.create(InputStream)可以自动根据文件头判断是.xls还是.xlsx，返回对应的 Workbook 实现类。

5.x 版本变化最大的地方是：关闭工作簿时强制要求关闭底层文件输入流。如果你的代码是new WorkbookFactory.create(new FileInputStream(file))且没有保存输入流引用，POI 5.x 会在关闭时因为没有输入流引用而无法正确释放文件句柄，Windows 系统上会出现文件被占用、无法删除的诡异问题。正确做法是保留输入流引用，并在关闭 workbook 之前关闭文件流。

try (InputStream in = new FileInputStream(file); Workbook workbook = WorkbookFactory.create(in)) { // 操作 workbook }

POI 5.2 以后，类路径下依赖的包也变了：poi-ooxml已经拉取poi-ooxml-lite、xmlbeans、commons-io等依赖。如果你只引入了poi而没有引入poi-ooxml，new XSSFWorkbook()会在运行期直接抛出NoClassDefFoundError，而不是编译期报错，这个特征很迷惑人。排查时先确认 Maven/Gradle 依赖齐全再说。

4.5 样式数量上限与字符串表膨胀

前面提到样式数量上限 65,490，实际业务中很难触达，但有一种情况例外：你用程序生成大量随机颜色单元格、逐单元格设置字体和颜色时，一秒就可能创建几百个样式。加上 Excel 对单元格字体数、边框数也有硬性限制——字体最大 65,490、边框最大 65,490、填充最大 65,490——总之这是个集体的上限。

字符串表（sharedStrings.xml）是另一个容易忽略的点。XSSFWorkbook 写入大量重复字符串时，POI 默认把字符串放入共享表。文件里存储的是“字符串索引”，这能节省体积。但问题在于：当你有大量唯一字符串时，sharedStrings.xml会变得巨大。我处理过一个场景：Excel 中某一列写入 5 万个随机 UUID，结果生成的文件体积异常大，打开速度也慢。后来改成让 UUID 列直接以“数字格式”写入或者压缩处理，才把文件瘦下来。

如果你的业务场景就是“大量唯一短字符串”，建议考虑在写入时设置Workbook的自定义字符串表策略，或者干脆用 SXSSFWorkbook，因为它默认不启用共享字符串表，字符串直接写入sheetN.xml，省去查表开销。

5. 工具选型与生态对比

5.1 为什么要拿 EasyExcel 跟 XSSFWorkbook 对比

近几年的技术讨论里，Apache POI 永远绕不开 EasyExcel。EasyExcel（阿里开源的 Excel 处理工具）底层其实是“重新包装了 POI 的 SAX 解析”能力，把读取和写入都做成流式模式，内存占用比直接new XSSFWorkbook低得多。很多新项目一上来就选 EasyExcel，把 POI 一棒子打死，这其实有失公允。

我的判断标准是看业务复杂度。

EasyExcel 的优势在于：API 基于注解，@ExcelProperty("字段名")标注实体类字段就能自动映射导入导出；内存占用极低。它官网宣传的“64M 内存读 75M 文件”虽然是极限场景下的数据，但流式模型确实省。

它的问题也很明显：对复杂 Excel 功能的支持没有 XSSFWorkbook 全面。比如多级嵌套表头、复杂的条件格式、数据透视表、自定义图表，这些在 EasyExcel 里要么不支持，要么需要 fallback 到底层 POI API 才能实现。另外 EasyExcel 的社区迭代节奏不稳，有时版本升级会破坏兼容性。

XSSFWorkbook 的价值在于“完整”和“可控”：它几乎能实现 Excel 的所有功能——图表、批注、宏、数据验证、条件格式、加密文档、VBA 操作。虽然内存占高、API 啰嗦，但它是你踩得最深的“底层根基”。EasyExcel 能做的，POI 一定能做；POI 能做的，EasyExcel 不一定能做。这是选型时最重要的判断依据。

5.2 人脸识别级别的“何时选 POI”清单

我梳理了一个快速决策清单，项目启动时直接对照选择：

我个人的倾向是：如果你在维护一个长期项目，优先把 XSSFWorkbook 打稳地基，之后再根据性能需求引入 EasyExcel 作为局部模块的优化方案。不要把“技术选型”变成“站队”，两种库并非互斥，甚至在同一个项目里同时出现也很正常。

5.3 未来扩展：从 Excel 到 CSV 到 PDF

说个题外话，也算经验之谈。很多人在做 Excel 导出的同一套业务里，会顺带被要求支持导出 CSV 甚至 PDF。CSV 本质是逗号分隔文本，直接用 POI 有点大材小用，写个BufferedWriter反而更快。但要注意 CSV 的 BOM 问题——Windows 上用 Excel 打开 UTF-8 编码的 CSV，中文会乱码，必须在文件头写入\uFEFFBOM 标记。

PDF 导出则完全是另一套技术栈，一般用 iText 或 Flying Saucer。如果你已经用 POI 做了 Excel 模板，再搞一套 PDF 模板，维护成本会翻倍。所以我在设计报表模块时，比较倾向“先出 Excel，再用 PDF 转换层适配”，把 Excel 作为数据的主载体，PDF 作为兼容输出。

拿 XSSFWorkbook 来说，它能直接读取你自己的 Excel 文件并提取数据交给 PDF 引擎，这一层耦合实际上是清晰且可控的。涉及图像、水印、排版复杂的场景，建议单独调用 PDF 库处理，不要把 POI 强行塞进 PDF 链路里。

6. 实战备忘录与经验沉淀

6.1 从零搭建一个报表导出功能的最小规范

如果你正打算在项目里加一个 Excel 导出功能，我基于踩坑经验给你总结出一套最小规范，照着做就不会出大问题：

1. 数据量预判先行：确认最多可能多少行。这个数字直接决定用 XSSFWorkbook 还是 SXSSFWorkbook。
2. 样式对象抽取复用：所有 CellStyle、Font、DataFormat 在循环外创建一次，循环内只引用。
3. 列宽策略固定化：不用autoSizeColumn，手动按列索引设置固定宽度，避免性能陷阱。
4. 日期格式显式设置：所有日期列都统一走一个dateStyle，避免用户看到序列数字。
5. 收尾统一关闭：Workbook.close()放在 try-with-resources 里，文件流同理，避免句柄泄漏。
6. 验证输出文件：生产代码交付前，一定要用真正的 Excel/WPS 打开验证一遍格式，别只在代码里打印看单元格个数。

第 6 条听起来很基础，但我见过的线上事故里有相当一部分是“代码能跑，Excel 打开报错”或“格式错位”，这都是自动化测试覆盖不到的地方。

6.2 几个能立刻提升开发效率的小技巧

第一，善用WorkbookFactory。它能根据输入流的内容自动判断.xls还是.xlsx，让代码兼容新旧 Excel 格式。你不需要在业务层自己判断扩展名再来new HSSFWorkbook或new XSSFWorkbook。

第二，开启 POI 的日志输出调样式问题。POI 的很多内部异常（如无效单元格引用、样式表溢出）在默认日志级别下是静默的。把log4j2.xml里org.apache.poi的级别调到DEBUG，在排查复杂问题时会看到更多内部上下文，比盲猜高效得多。

第三，Excel 的行列索引永远是 0-based，但 Excel GUI 显示是 1-based。很多新人在这里翻车：代码里createRow(1)以为创建的是“第一行”，实际上已经写到了表头下一行。写代码时建议在行首加注释说明当前处理的是“第 N 行（0-based）”。

第四，磁盘落盘意识。凡是操作大型 Excel 的功能，最好先写到本地临时文件再上传/下载，而不是直接内存一把梭。比如workbook.write(response.getOutputStream())这种写法在数据量稍大时会因为网络慢导致输出流迟迟不 flush，内存里的 DOM 树长时间不释放，最终拖垮服务。我的习惯是先在/tmp生成文件，再通过FileInputStream输出到响应流，写完后立即删除临时文件。

6.3 我对 XSSFWorkbook 的一点使用心得

写了这么多年 Java 报表相关代码，我对 XSSFWorkbook 的定位越来越清晰：它是一个底层能力极强、但需要你主动管理复杂度的工具。新手阶段，大家喜爱它是因为上手快、API 直白；到了项目复杂起来，发现内存和性能问题后，又开始嫌弃它。但实践经验多了以后你会发现，任何工具都有它的边界，XSSFWorkbook 的边界在于“整树驻留内存”，而这个边界完全可以通过业务拆解来规避——比如限制单文件导出行数、拆分多 Sheet、配置合理的 JVM 堆和 GC 策略。

如果你做的事情只是定期导出几十万行报表，我建议你在 POI 上层再封装一层自己的工具类，把样式管理、日期格式化、列宽策略、Workbook 类型自动选择这些细节全部收拢到一个门面方法里。业务代码永远只关心“我要导出哪张表、数据从哪里来”，不用关心底层是 XSSFWorkbook 还是 SXSSFWorkbook。这样才是在长期项目里用 POI 的正确姿势，而不是每次接到报表需求都从零开始写一遍踩坑代码。

我最后再分享一个实操小技巧给所有做报表导出的朋友：如果你在使用XSSFWorkbook填充模板时发现某个单元格的值怎么都填不进去，先检查这个单元格是不是被合并区域覆盖了。POI 会拒绝向合并区域内的非左上角单元格写值，或者写了也被 Excel 隐藏。这个排查点不好定位，但一旦知道规律，以后遇到类似问题一眼就能识别。做 Excel 工具，耐心和技术同样重要。