Apache POI实战：Excel大数据导出与Word表格宽度设置

看到标题里的 Apache POl，我先默认最后一位是小写 L 手滑。你要找的十有八九是 Apache POI，Java 圈处理 Office 文档最老牌的那个库。我第一次接触 POI 是在一个导出十万行 Excel 报表的需求里，当时没搞清楚 HSSFWorkbook、XSSFWorkbook、SXSSFWorkbook 的区别，结果内存直接爆掉，后来花了两天把 POI 的底层模型和 OOXML 结构捋了一遍才算踏实。这篇内容不讲官方文档已经写烂的 Hello World，而是把真正影响使用体验的模块选择、Maven 依赖、Excel 大数据导出、Word 表格宽度这几个痛点一次性说透，顺带把搜索时容易撞车的地图 POI、5G POI 这些概念也分清。

1. 搜“POI”搜出来的三种完全不同的东西

1.1 Apache POI 到底是个什么库

Apache POI 是一个纯 Java 实现的开源库，用于读取和写入 Microsoft Office 格式的文档。它的名字来自“Poor Obfuscation Implementation”，意思是微软的二进制文档格式做得很混乱，POI 以一种“不优雅但能用”的方式把它们解析了出来。早年 Office 的 .xls、.doc、.ppt 是封闭二进制格式，.docx、.xlsx 本质是 ZIP 压缩包加一堆 XML，POI 把两条技术线都覆盖了。

POI 的模块分配非常清晰，一般用到的是下面这几个：

什么意思？就是同一个库既管老 Office，也管新 Office。早年项目里只能用 HSSFWorkbook 操作 .xls，现在大部分业务已经切到 .xlsx，直接用 poi-ooxml 模块里的类就行。如果你只听过 HSSFWorkbook，说明你搜索到的资料至少是十年前的老教程了。

1.2 地图兴趣点和 5G 的 POI 别搞混

很多人搜“POI 数据集”会搜到大量地图坐标、兴趣点数据，那个全称是 Point of Interest，比如高德、百度的 POI 数据，做地理信息系统的人天天用。这个跟 Apache POI 没有关系，唯一的共同点就是缩写都叫 POI。

还有一个容易撞车的是通信领域里的 POI，尤其是 5G 站点相关的内容。最近不少人搜“5G BBU、RRU、POI”，这里的 POI 是 Point of Interface，在基站系统里做多系统合路或者信号接入用的，跟 Java 后端、Office 文件处理完全不搭边。

所以如果你是为了导出 Excel、生成 Word、解析 PPT 找到这篇文章，那方向对了。如果你是为了地图坐标和 5G 设备资料来的，建议换个关键词继续搜。

2. 环境准备：Maven 坐标、JDK 版本和依赖冲突

2.1 一条 poi-ooxml 依赖起步

现在用 POI 写 .xlsx，只需要引入一个 poi-ooxml 包，它会把基础的 poi 模块和一堆 OOXML schema 依赖自动带进来。以 Maven 3.9+ 为例，pom.xml 里这样配置：

xml复制<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>5.2.5</version>
</dependency>

如果你只处理老的 .xls，理论上只要 poi 模块就够了，但现实项目里很难只面对一种格式，所以直接上 poi-ooxml 是最省事的做法。项目里经常需要同时读写 Word 和 PowerPoint，poi-ooxml 也把这些 OOXML 类都包含了。POI 5.x 对 Java 8 以上都很友好，我用 JDK 17 没踩过什么大坑，直接用最新稳定分支就行。

有些人会看到 poi-ooxml-lite 这个变体，它是把完整版里的 OOXML schema 精简了一部分，体积小一点。但如果你要做复杂的 Word 表格自定义、Visio 解析之类的操作，精简版可能会缺少某些 schema 类型，不建议一开始就上精简版。

2.2 xmlbeans 和 commons-compress 的冲突

POI 依赖关系里最容易出问题的是 xmlbeans、commons-compress、log4j-api 这几个。项目里如果已经有旧版本的 xmlbeans，或者某个 Spring Boot 老版本自带了一份不兼容的 commons-compress，运行时就会出现奇奇怪怪的 NoClassDefFoundError、NoSuchMethodError，最典型的是：

text复制java.lang.NoSuchMethodError: org.openxmlformats.schemas.wordprocessingml.x2006.main.CTBody.isSetSectPr()Z

这种错误通常不是代码写错了，而是依赖版本被全局管理到了旧版本。排查的时候别急着改代码，先看依赖树：

bash复制mvn dependency:tree -Dincludes=org.apache.poi:*

然后看项目根 pom.xml 里有没有通过 dependencyManagement 强制指定了跟 POI 不兼容的 xmlbeans 版本。我的处理习惯是：POI 相关的传递依赖不手动覆盖，除非项目里真有冲突必须锁定，那就以 POI 当前版本对应的传递依赖列表为基准去对齐。

还有一个容易忽略的点：公司内部如果自建了 Maven 私服，中央仓库同步不全的时候，拉不到 5.2.5 的坐标也会让你怀疑人生。先确认私服里有没有这个版本，再怀疑代码问题。

3. Excel 报表：从 HSSFWorkbook 到 SXSSFWorkbook

3.1 三种 Workbook 怎么选

Excel 在 POI 里有三套 API，刚入门的同学经常搞混，我直接按场景拆开：

HSSFWorkbook 只能操作 .xls，行数上限 65536，现在基本属于历史遗留场景。XSSFWorkbook 是平时最常用的，支持 .xlsx，单表最多可以到 1048576 行，但它是基于 DOM 的内存模型，整个 Excel 的单元格对象都会堆在 JVM 里。几万行的数据没问题，一旦到几十万行，内存占用会非常难看。

SXSSFWorkbook 是 POI 针对写场景提供的流式 API，它只保留最近 N 行在内存里，前面的行会刷到临时文件，所以导出再大的数据也不会撑爆堆内存。代价是它只支持写入，不支持读取已有 Excel，也不是所有 API 都支持。

3.2 小报表用 XSSFWorkbook 的完整示例

如果报表数据量在几万行以内，老老实实用 XSSFWorkbook，代码直接、样式好控制。我一般会把表头样式、日期格式提前定义好，避免在循环里重复创建样式对象。

java复制try (XSSFWorkbook workbook = new XSSFWorkbook();
     FileOutputStream fos = new FileOutputStream("report.xlsx")) {

    XSSFSheet sheet = workbook.createSheet("订单");

    CellStyle headerStyle = workbook.createCellStyle();
    XSSFFont headerFont = workbook.createFont();
    headerFont.setBold(true);
    headerStyle.setFont(headerFont);
    headerStyle.setFillForegroundColor(IndexedColors.GREY_25_PERCENT.getIndex());
    headerStyle.setFillPattern(FillPatternType.SOLID_FOREGROUND);

    String[] headers = {"订单号", "客户", "金额", "下单时间"};
    XSSFRow headerRow = sheet.createRow(0);
    for (int i = 0; i < headers.length; i++) {
        XSSFCell cell = headerRow.createCell(i);
        cell.setCellValue(headers[i]);
        cell.setCellStyle(headerStyle);
    }

    CellStyle dateStyle = workbook.createCellStyle();
    dateStyle.setDataFormat(workbook.getCreationHelper()
            .createDataFormat().getFormat("yyyy-MM-dd HH:mm:ss"));

    for (int i = 0; i < 1000; i++) {
        XSSFRow row = sheet.createRow(i + 1);
        row.createCell(0).setCellValue("ORD" + i);
        row.createCell(1).setCellValue("客户" + i);
        row.createCell(2).setCellValue(100.5 * i);
        XSSFCell dateCell = row.createCell(3);
        dateCell.setCellValue(new Date());
        dateCell.setCellStyle(dateStyle);
    }

    for (int i = 0; i < headers.length; i++) {
        sheet.setColumnWidth(i, 20 * 256);
    }

    workbook.write(fos);
}

这里 sheet.setColumnWidth(i, 20 * 256) 里的 256 是 POI 的列宽单位，一个单位等于一个英文字符宽度的 1/256。20 * 256 就是让列宽大致容纳 20 个字符。中文宽度会大一点，所以涉及中文的时候我会再乘以 1.2 到 1.5 的系数，具体看实测效果。

3.3 十万行数据用 SXSSFWorkbook

如果数据量到了十万、百万行，XSSFWorkbook 会非常吃力。我自己遇到过一次导出二十万行、十几列的业务，用 XSSFWorkbook 直接堆到 JVM 老年代溢出。换成 SXSSFWorkbook 之后，内存稳定在几十 MB 级别。

java复制SXSSFWorkbook workbook = new SXSSFWorkbook(100);
try {
    SXSSFSheet sheet = workbook.createSheet("big-data");

    for (int i = 0; i < 200000; i++) {
        SXSSFRow row = sheet.createRow(i);
        row.createCell(0).setCellValue(i + 1);
        row.createCell(1).setCellValue("订单" + i);
        row.createCell(2).setCellValue(100.0 * i);
    }

    try (FileOutputStream fos = new FileOutputStream("big-report.xlsx")) {
        workbook.write(fos);
    }
} finally {
    workbook.dispose();
    workbook.close();
}

这里的 new SXSSFWorkbook(100) 表示内存里只保留 100 行，超过的行会由 POI 在内部自动刷到临时文件。dispose() 负责清理 SXSSF 用的临时文件，很多人只写 close() 不写 dispose()，在长时间运行的服务里可能会留下临时文件垃圾。这是 SXSSF 特有的操作，XSSFWorkbook 没有也不需要。

还有一个关键点：SXSSFWorkbook 不能用来读已有模板。如果你需要打开一个模板文件、填充数据再导出，老老实实用 XSSFWorkbook 读文件，否则会直接抛异常或拿不到数据。

3.4 写 Excel 的行列样式陷阱

循环写大报表的时候，最忌讳在循环里面反复 createCellStyle()。每个 CellStyle 在 POI 里都是一个独立对象，分布在 workbook 的样式表里，样式创建太多会让文件体积膨胀，也可能触发性能问题。正确做法是提前创建好几种固定样式，循环里只赋值引用。

另外，合并单元格和边框样式的组合也容易踩坑。比如合并区域之后，只有左上角单元格的样式会被保留，其他单元格的边框、背景色很容易丢失。如果遇到合并后样式不对，先把合并区域内所有单元格都设成同样的样式，再执行合并，比合并之后再补样式靠谱得多。

4. Word 表格单元格宽度：这次我把底层 XML 也讲清楚

4.1 宽度设置为什么有三处

Word 表格的宽度问题可能是 POI 里被问得最多的一个点。有人设置了 cell.setWidth("2400")，打开 Word 发现没生效，或者只在某些 Word 版本里生效，换个软件打开又乱了。原因很简单：WordprocessingML 里表格宽度由三处共同决定。

• tblW：表格整体宽度，定义在 tblPr 里。
• tblGrid：表格网格列宽，定义在 tblGrid 里的若干个 gridCol。
• tcW：每个单元格的宽度，定义在每个单元格的 tcPr 里。

三者的关系可以理解成一个布局约定：tblW 告诉渲染器表格总宽是多少，tblGrid 定义每一列的基础宽度，tcW 是每个单元格自己声明的宽度。如果只改 tcW，不改 tblGrid，某些渲染器会优先按网格宽度布局，你的设置就“没生效”了。

4.2 直接操作 CTTbl 的通用方法

所以我的习惯是，涉及 Word 表格宽度就直接操作底层 XML 对象 CTTbl，一次性把三处都写上。POI 的高层 API 虽然方便，但在这里反而容易造成信息不完整。

java复制import org.apache.poi.xwpf.usermodel.*;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.*;
import java.math.BigInteger;

private void setupTableWidth(XWPFTable table, int[] widths) {
    int total = 0;
    for (int w : widths) {
        total += w;
    }

    // 1. 设置表格整体宽度
    CTTblPr tblPr = table.getCTTbl().isSetTblPr()
            ? table.getCTTbl().getTblPr()
            : table.getCTTbl().addNewTblPr();
    CTTblWidth tblW = tblPr.isSetTblW() ? tblPr.getTblW() : tblPr.addNewTblW();
    tblW.setType(STTblWidth.DXA);
    tblW.setW(BigInteger.valueOf(total));

    // 2. 设置 tblGrid 网格列宽
    CTTblGrid grid = table.getCTTbl().isSetTblGrid()
            ? table.getCTTbl().getTblGrid()
            : table.getCTTbl().addNewTblGrid();
    for (int i = 0; i < widths.length; i++) {
        CTTblGridCol gridCol = grid.sizeOfGridColArray() > i
                ? grid.getGridColArray(i)
                : grid.addNewGridCol();
        gridCol.setW(BigInteger.valueOf(widths[i]));
    }

    // 3. 设置每个单元格的 tcW
    for (XWPFTableRow row : table.getRows()) {
        List<XWPFTableCell> cells = row.getTableCells();
        for (int i = 0; i < cells.size(); i++) {
            XWPFTableCell cell = cells.get(i);
            CTTcPr tcPr = cell.getCTTc().isSetTcPr()
                    ? cell.getCTTc().getTcPr()
                    : cell.getCTTc().addNewTcPr();
            CTTblWidth tcW = tcPr.isSetTcW() ? tcPr.getTcW() : tcPr.addNewTcW();
            tcW.setType(STTblWidth.DXA);
            tcW.setW(BigInteger.valueOf(widths[i % widths.length]));
        }
    }
}

这里宽度单位是 twips，也就是 Word XML 里的 DXA。1 英寸等于 1440 twips，1 厘米约等于 567 twips。A4 纸默认页边距下的正文宽度大约是 9000 twips 上下，所以常见的三分列可以用 2400、3300、3300 这种组合。表格总宽算好之后写在 tblW，不会超出页面。

顺序上我建议先建表格、确定行列数，再调这个方法。新建表格的 tblGrid 一般已经有对应数量的 gridCol，直接把每个 gridCol 的 W 属性覆盖掉即可。

4.3 cell.setWidth 什么时候够用

并不是说 cell.setWidth("2400") 完全没用，在简单场景下它是有效的。XWPFTableCell.setWidth(String) 最终改的是 tcW，对于不依赖 tblGrid 的渲染器已经够了。但如果你发出去的 Word 要兼容不同版本的 Microsoft Word、WPS 或者 LibreOffice，建议还是用上面那种把三处都设置好的方式，兼容性会好很多。

类似的还有表格整体宽度，XWPFTable 有 setWidth(int) 方法，它设置的是 tblW。只要你的列宽总和不等于这个值，还是会出现渲染差异。最好的做法就是自己把网格、单元格、总宽当成一个整体来设置。

4.4 Word 里中文字体和单元格垂直居中的附带坑

表格宽度之外，做 Word 报表时还有两个高频问题：中文乱码显示成方块、单元格内容不垂直居中。

第一个问题其实是字体设置问题，POI 写入的文字默认可能不带中文字体，Windows 下用默认字体渲染还好，换到 macOS 或线上服务生成再下载到本机，容易变成宋体方块。处理方式是给 run 显式设置中文字体：

java复制XWPFRun run = cell.getParagraphs().get(0).createRun();
run.setText("中文内容");
run.setFontFamily("宋体");
run.setFontSize(10);

第二个问题，单元格垂直居中需要设置 XWPFTableCell：

java复制cell.setVerticalAlignment(XWPFTableCell.XWPFVertAlign.CENTER);

如果你的表格内容包含多行段落，记得先 setVerticalAlignment 再填充内容，这种属性设置在 POI 里经常因为顺序不同而产生奇怪的结果。

5. 真正用过才会踩的坑：日期、公式、模板与内存

5.1 Excel 里日期变数字

POI 里往单元格写入 java.util.Date 容易踩的问题不是写入失败，而是打开 Excel 后看到一串数字。原因是 Excel 的日期本质上是数值，日期显示完全依赖单元格格式。如果你不设置 CellStyle 的 dataFormat，POI 默认可能按纯数值写入，10 月 1 日就显示成 45000 之类的东西。

正确的做法是先创建一个带日期格式的 CellStyle，再把时间和样式一起设到单元格上：

java复制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);

读取的时候反过来，用 DateUtil.isCellDateFormatted(cell) 判断它是不是日期格式，再调用 getDateCellValue()，否则很容易把日期单元格读成数值。

5.2 公式写进去打开不计算

POI 可以写公式，比如 cell.setCellFormula("SUM(A1:A10)")。但公式写完之后，有些 Excel 打开文件可能显示计算结果，有些可能显示 0，需要手动触发一次重算。这不是 POI 没写好，而是 OOXML 文件里缺少“打开时强制重新计算”的标记。

处理方法是在写文件之前调用：

java复制workbook.setForceFormulaRecalculation(true);

如果你在服务端需要拿公式计算结果去参与后续逻辑，那就不能依赖 Excel 打开时重算，而是用 POI 的 FormulaEvaluator 先算一遍：

java复制FormulaEvaluator evaluator = workbook.getCreationHelper().createFormulaEvaluator();
CellValue value = evaluator.evaluate(cell);

需要强调一点：SXSSFWorkbook 面向的是快速写入，公式重算的支持不如 XSSFWorkbook 完整。如果业务里公式逻辑很重，优先用 XSSFWorkbook。

5.3 读模板填数据别用错对象

很多项目为了统一报表样式，会先做一个 Excel 模板，然后让 POI 读取模板、替换占位符、导出新文件。这个场景只能用 XSSFWorkbook，千万别换成 SXSSFWorkbook，因为 SXSSF 是流式写模型，本身就不支持读取已有文件。

模板填充的基本套路是遍历所有单元格，找到包含占位符的文本再替换：

java复制try (XSSFWorkbook workbook = new XSSFWorkbook(new FileInputStream("template.xlsx"))) {
    XSSFSheet sheet = workbook.getSheetAt(0);
    for (Row row : sheet) {
        for (Cell cell : row) {
            if (cell.getCellType() == CellType.STRING) {
                String text = cell.getStringCellValue();
                if (text.contains("{{name}}")) {
                    cell.setCellValue(text.replace("{{name}}", "张三"));
                }
            }
        }
    }
    try (FileOutputStream fos = new FileOutputStream("output.xlsx")) {
        workbook.write(fos);
    }
}

这里有一个小坑：单元格的 CellType 判断要用 POI 5.x 的 CellType.STRING，不要再用老教程里的 Cell.CELL_TYPE_STRING，后者在 4.x 之后就标记过时了。如果你在项目里混用了新旧 API，编译不报错但代码风格会比较混乱。

5.4 双循环里别反复 new 样式

前面提到了样式复用，这在 Excel 和 Word 场景里都成立。样式对象的创建成本不低，而且每个样式对象都会增加文件元数据。特别是双层循环遍历行列填数据的时候，如果每个格子都 createCellStyle()，文件体积和生成耗时都会成倍增长。

我的习惯是在循环外把需要的样式都建好，放进一个 Map 或者直接声明成方法局部变量：

java复制CellStyle style = workbook.createCellStyle();

循环里只调 cell.setCellStyle(style)。如果不同列需要不同对齐方式，最多建两到三种样式，不要按行按列地建。

6. Apache 生态里那些容易和 POI 混的名字

6.1 Apache Camel 与 camel-poi

做系统集成的人经常会在项目里看到 Apache Camel，它和 POI 不是同一个东西，但在文件处理场景里会合作。Camel 是一个集成框架，负责把各种系统通过路由串起来；POI 负责读写 Office 文件。Camel 官方有基于 POI 封装的数据格式扩展，在路由里可以更方便地生成 Excel 文件。

如果你的项目里已经用了 Apache Camel，并且需要把消息转成 Excel，可以直接查一下当时 Camel 版本对应的 camel-poi 组件文档。不同 Camel 大版本的依赖坐标差异挺大，不要直接照抄网上老版本的配置，否则打包阶段就能看到一堆找不到类的问题。

6.2 Apache Hop 的 Excel 步骤

Apache Hop 是开源 ETL 工具，做数据抽取转换加载。它里面处理 Excel 的输入输出步骤，底层很大程度就是基于 POI 实现的。所以如果你在用 Hop 做数据同步，Excel 步骤报错时，日志里出现 org.apache.poi 开头的异常并不奇怪，本质还是 POI 解析 Excel 时出了问题。

这时候你先别急着怀疑 Hop 本身，先检查 Excel 文件是不是真的损坏、是不是老 .xls 格式、是不是包含 Hop 当前依赖的 POI 版本不支持的复杂特性。ETL 场景里最常见的报错是“文件格式扩展名和实际内容不一致”，也就是文件后缀是 .xlsx，实际里面是别的格式，POI 直接拒绝解析。

6.3 Apache Maven 和 Apache HTTP Server

还有人搜“apache 安装与配置”、“apache 屏蔽垃圾爬虫”找到这里，那些基本都是 Apache HTTP Server，也就是开源的 Web 服务器，跟 Apache POI 没有关系。Apache 软件基金会下面项目太多，名字前面都挂着 Apache，搜索的时候一定要把后半截看完整。Maven 是构建工具，HTTP Server 是 Web 服务器，POI 是 Office 文档处理库，三者共用 Apache 前缀，但技术栈和应用场景天差地别。

如果你确实是想在 Java 服务里屏蔽垃圾爬虫，那是另一个话题，可以配合拦截器和 IP 黑名单做，跟 POI 无关。

我现在的固定套路是：先确认要处理的文件格式，再选模块；Excel 数据量大就提前上 SXSSFWorkbook，数据量小就用 XSSFWorkbook；Word 表格涉及宽度直接操作 CTTbl，不做“看起来能用”的简化。POI 本身不复杂，复杂的是 Office 文档格式里那些隐性的布局规则。把这些底层规则摸清之后，不管做 Excel 报表还是 Word 文档生成，心里都会踏实很多。