企业官网建设流程全解析

1. 先把“解锁版”这三个字说清楚

做 Java 后端的人，几乎绕不开 Word 文档这个需求。合同批量生成、报表导出、简历解析、公文套红、发票排版、投标文件组装，只要业务沾上“要一份能给人看的纸质感文件”，最后都会落到 Java 操作 Word 这个坑里。市面上被讨论最多的两个商业组件，一个是Spire.Doc for Java，一个是Aspose.Words for Java，前者国内技术社区资料多、上手快，后者功能厚度和格式兼容性更猛、历史也更长。它们确实能解决大量开源方案搞不定的问题，比如高保真转 PDF、复杂页眉页脚、域代码、图表、SmartArt、邮件合并。

但我要先把一句话放在最前面：这篇文章不会、也不应该提供任何绕过授权的手段。所谓“全功能解锁版”“免费下载绿色版”，本质上都是修改了厂商授权校验逻辑的二次打包产物，用它在生产环境里跑，属于把整个项目架在火药桶上。我更想聊的是——这两个库到底强在哪、弱在哪，什么场景值得为它掏钱，什么场景用开源方案就够了，以及在合规前提下怎么把成本压到最低。这篇内容适合正在做文档模块技术选型的后端、正在被“模板套打”折磨的中级开发，也适合需要给团队做技术决策的技术负责人。看完你至少能判断出：你这个需求，到底该买、该换、还是该自己写。

1.1 商业文档组件为什么敢收费

很多人不理解，一个“往 Word 里填字”的库，凭什么卖钱。这里的关键认知差异是：开源库大多在做XML 结构操作，商业库在做文档排版引擎。这两件事的工程量差了一个数量级。

以 Apache POI 为例，它把 .docx 当成一个 zip 包解开，里面对应 document.xml、styles.xml、numbering.xml、rels 等一堆部件，你操作的是 OOXML 的节点树。所以“往指定段落塞一段文字”很好办，但“这个段落自动换行后会不会溢出到第二页”“表格跨页后表头要不要重复”“这段文字用宋体小四在 A4 页面宽度下第几个字开始折行”，POI 是不管的——它根本没有排版引擎，也就没有分页信息。

商业库则内置了布局计算能力。你给它页面尺寸、页边距、字体、行距，它能算出每行放多少字、每页放多少行、元素落到第几页第几行。这才是“导出 PDF 一页都不差”的根本原因。Spire.Doc 和 Aspose.Words 都属于这一类，所以它们按开发者席位和部署实例收费，逻辑上是卖引擎而不是卖 API。

理解这一点很重要，因为它决定了你的选型判断标准：如果你只是要生成一个结构简单的 docx 给人再编辑，开源库完全够；如果你要“所见即所得地输出成品 PDF 且版式不能崩”，那基本只能上商业库或者自己接一个 Office/LibreOffice 的无头渲染服务。

1.2 破解包的隐性成本：三个真实维度

我在过去几年里见过不少团队在项目初期图省事，直接用了来路不明的 jar 包，最后付出的代价远超那点授权费。这里展开说三个维度，都是实打实会咬人的。

第一个是供应链维度。商业 jar 包在正常渠道是带签名、带完整性校验的，而二次打包的版本被替换掉了字节码。你没法审计它到底往里面加了什么——可能只是去掉了校验，也可能顺手加了读环境变量、读配置文件、在特定条件下向外发请求的逻辑。这类东西静态扫描不一定报，因为它的行为可以藏在正常的 IO 调用里。一旦进到生产环境，你连排查方向都没有。

第二个是版本维度。这类包通常锁死在某个旧版本上，因为新版本校验逻辑变了，没人愿意再改一遍。而文档格式处理恰恰是最需要跟版本的领域——新版本 Office 保存出来的 docx 可能带新的命名空间、新的图表结构，旧版本库解析直接抛异常或者静默丢内容。你以为省了钱，实际上是把自己钉死在一个再也升不上去的版本上，遇到 bug 只能等别人施舍。

第三个是维护维度。出了问题你没法提工单。厂商的技术支持是跟着授权走的，而没有授权就没有对话通道。文档处理这类问题往往非常具体：“某个客户给的模板里有个嵌套表格加合并单元格，转 PDF 后边框线丢了一根”，这种问题只有厂商能查，社区里没人帮得了你。我们团队曾经为一个页眉图片缩放比例的问题卡了整整三天，最后是靠正式授权走工单半天解决的，那三天的人力成本早就超过授权费了。

注意：项目里如果已经存在来源不明的商业 jar，第一件事不是删，而是先查清调用点、评估替换成本，同时把依赖树打出来确认没有传递依赖被污染。直接删很容易把构建搞崩。

1.3 合规前提下的四条低成本路径

说完成本，也得说解决方案，不然就是站着说话。实际可走的路有这么几条，按成本从低到高排：

路径一：先用试用授权把验证做完。两款库都提供带水印或者限页数的免费试用模式，功能是全的。做法是先用试用版把 POC 跑通、把模板调好、把性能压测做完，确认“确实能解决我的问题”之后再谈采购。这个阶段完全合规，也不花钱。

路径二：评估社区版或精简版。Spire 系列有 Free 版本，限制是页数和段落数（具体限制以官方文档为准），适合小文档场景；Aspose 没有免费版但有按用量计费的云 API 形态，适合调用量不大、又不想本地部署的场景。

路径三：开源方案组合兜底。Apache POI 负责 docx 结构读写，docx4j 负责更复杂的 OOXML 操作和部分转换，OpenPDF 或 PDFBox 负责 PDF 侧收尾。这条路的工作量明显更大，但零授权成本，且完全可控。

路径四：外挂渲染服务。用 LibreOffice 无头模式做 docx→pdf 转换，Java 侧只负责生成 docx。这个方案的坑在于服务器上要装全套中文字体、转换并发要排队、复杂模板可能渲染偏差，但成本极低，很多中小项目就是这么干的。

我的建议是：先用路径一验证，再用路径三或四跑 MVP，等业务量起来、文档质量成为硬指标了，再走采购。别一上来就买，也别一直不买。

2. 两款商业库与开源方案的能力边界

选型这件事，最怕的是拿着一张“功能对比表”拍脑袋。实际上真正决定成败的往往不是“支持不支持”，而是“支持到什么程度”“边界情况怎么处理”。这一章我按实际踩过的场景来拆。

2.1 功能矩阵：谁擅长什么

下面这张表是我根据几个实际项目整理的能力对照，重点标注了“能用”和“好用”的区别，因为很多库是“能读能写但渲染不准”。

从表里能看出一个很清晰的定位差异：POI 和 docx4j 解决的是“文件结构”问题，Spire 和 Aspose 解决的是“版式呈现”问题。如果你的输出物是要给人编辑的 docx，前者够用；如果要输出成品 PDF 或需要精确控制版面，后者才是对的工具。

Spire.Doc 的优势在于 API 设计更贴近中文开发者的直觉，比如replace方法做占位符替换就是一行；Aspose.Words 的优势在于边界情况的覆盖度，尤其是那种“客户给的模板里有十年前留下的奇怪结构”的场景，Aspose 的容错率明显更高。

2.2 性能与资源占用：上线后才会暴露的差异

本地跑 demo 的时候，两个库都是毫秒级返回，看不出区别。真正拉开差距的是批量场景：一次导出 500 份合同、一天处理 2 万份简历、大促期间生成 10 万张对账单。

我在一个批量生成场景里做过粗略对比（同一台 4C8G 的机器、同一个 30 页含 12 个表格的模板、单线程跑 200 次取平均）：

数据只能作为量级参考，不同模板、不同版本差别很大，但有两个结论是稳定的：

第一，转 PDF 是真正的性能瓶颈。生成 docx 再快也没用，因为 PDF 转换要做完整排版计算，耗时是生成的好几倍。所以批量场景的设计重点不是“怎么把 docx 生成得更快”，而是“怎么把 PDF 转换并行化、怎么加缓存、怎么削峰”。

第二，商业库的对象必须显式释放。Aspose 的Document和 Spire 的Document底层都持有非托管资源，用完不释放，堆外内存会一路涨上去。JVM 的 GC 看不到这部分，你只会看到容器被 OOMKilled，堆 dump 里干干净净什么都查不出来——这个坑后面第 5 章会详细讲。

2.3 选型决策：按业务场景倒推

与其纠结功能列表，不如直接回答三个问题：

问题一：你的输出物是 docx 还是 PDF？如果最终交付给用户的是 docx（让他自己再改），那 POI 大概率够用，省下的钱可以投到别处。如果最终是 PDF，而且客户会拿着放大镜看版式，直接上商业库，别浪费时间。

问题二：模板是你能控制的，还是客户给的？自己能控模板的话，结构可以设计得很“干净”，开源库容易搞定；客户给模板的话，你永远不知道里面藏着什么，商业库的容错能力值这个价。

问题三：并发量和时效要求是什么？一天几百份，怎么都能跑；一天几十万份，那就得考虑队列、缓存、预热、甚至拆分成独立服务。

我的经验是，80% 的项目其实用 POI 就能做完，剩下 20% 里有一半可以用 LibreOffice 无头转换解决，真正必须买商业授权的可能只有 10%。但恰恰是这 10% 的项目，用开源方案硬扛会导致项目延期和质量事故。判断标准很朴素：如果文档质量直接关联收入或者合规，那就买。

3. 环境准备与最小可运行工程

这一章开始上手。我用 Maven 做依赖管理，Spring Boot 项目和非 Spring 项目都适用。

3.1 依赖与仓库配置

商业组件通常不在 Maven 中央仓库，需要单独配置仓库地址。具体地址以厂商官网文档为准，我这里给出的是结构模板，实际项目里把它填到settings.xml的 mirror 或者项目 pom 的 repositories 里。

<repositories> <repository> <id>vendor-repo</id> <url>https://厂商官方仓库地址/</url> <releases><enabled>true</enabled></releases> <snapshots><enabled>false</enabled></snapshots> </repository> </repositories>

依赖本身：

<!-- Spire.Doc for Java --> <dependency> <groupId>com.e-iceblue</groupId> <artifactId>spire.doc</artifactId> <version>以官网最新稳定版为准</version> </dependency> <!-- Aspose.Words for Java，注意 jdk17 分类器要跟运行环境匹配 --> <dependency> <groupId>com.aspose</groupId> <artifactId>aspose-words</artifactId> <version>以官网最新稳定版为准</version> <classifier>jdk17</classifier> </dependency> <!-- 开源兜底方案 --> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>5.2.5</version> </dependency>

注意：Aspose.Words 的classifier一定要和你的 JDK 主版本匹配，jdk8、jdk11、jdk17 是不同的产物。选错了不会编译报错，而是在运行时抛一些莫名其妙的反射异常，非常难查。这是新手最常踩的坑之一。

另外提醒一句：这类库的 jar 体积都不小，Aspose.Words 打包后动辄几十兆。如果你的应用要做成体积敏感的镜像，建议把文档处理单独拆成一个服务，不要和主业务揉在一起。

3.2 授权文件加载：一个必须做对的初始化

授权文件加载看着简单，但有两个细节非常关键：只能加载一次，以及必须在任何文档操作之前。

@Component public class DocumentLicenseInitializer { private static final Logger log = LoggerFactory.getLogger(DocumentLicenseInitializer.class); @PostConstruct public void init() { try { // 授权文件从配置中心或挂载目录读取，不要打进 jar 包 File licenseFile = new File(System.getProperty("doc.license.path", "/opt/app/conf/doc.license")); if (!licenseFile.exists()) { log.warn("未找到授权文件，将以试用模式运行，输出可能带水印或受页数限制"); return; } try (InputStream in = new FileInputStream(licenseFile)) { com.aspose.words.License asposeLicense = new com.aspose.words.License(); asposeLicense.setLicense(in); } try (InputStream in = new FileInputStream(licenseFile)) { com.e_iceblue.spire.doc.License spireLicense = new com.e_iceblue.spire.doc.License(); spireLicense.setLicense(in); } log.info("文档组件授权加载完成"); } catch (Exception e) { // 这里不要吞异常，也不要把异常堆栈直接打给前端 log.error("文档组件授权加载失败，请检查授权文件有效性", e); } } }

三个实操要点：

一是授权文件放容器外挂载，不要打进 jar。打进 jar 意味着换授权要重新打包发版，而且授权文件往往跟环境绑定，开发和生产的不是同一个。

二是加载失败不要静默。很多人写成 try-catch 吞掉异常，结果生产环境跑了两周才发现一直在试用模式，输出文件全部带水印。至少要打 error 日志，最好加一个健康检查端点暴露当前授权状态。

三是重复加载是有代价的。Aspose 的License.setLicense每次调用都会做一次校验和内部状态重置，放在请求里调用会明显拖慢吞吐。我见过有人在 Controller 里每次请求都 new 一个 License 设置一遍，QPS 直接掉一半。

3.3 第一份程序生成的 Word 文档

先跑通最小闭环，建立信心。Spire.Doc 的写法：

public void createSimpleDoc(String outputPath) throws Exception { Document doc = new Document(); Section section = doc.addSection(); Paragraph title = section.addParagraph(); TextRange titleText = title.appendText("项目交付确认单"); titleText.getCharacterFormat().setFontName("宋体"); titleText.getCharacterFormat().setFontSize(18f); titleText.getCharacterFormat().setBold(true); title.getFormat().setHorizontalAlignment(HorizontalAlignment.Center); Paragraph body = section.addParagraph(); TextRange bodyText = body.appendText("本确认单由系统自动生成，请核对后签字确认。"); bodyText.getCharacterFormat().setFontName("宋体"); bodyText.getCharacterFormat().setFontSize(12f); body.getFormat().setFirstLineIndent(24f); try { doc.saveToFile(outputPath, FileFormat.Docx); } finally { doc.dispose(); // 必须显式释放 } }

Aspose.Words 的等价写法，用的是DocumentBuilder，这个链式 API 我个人更喜欢，因为它把“光标在文档里的位置”这个概念显式化了：

public void createSimpleDoc(String outputPath) throws Exception { Document doc = new Document(); DocumentBuilder builder = new DocumentBuilder(doc); builder.getParagraphFormat().setAlignment(ParagraphAlignment.CENTER); builder.getFont().setName("宋体"); builder.getFont().setSize(18); builder.getFont().setBold(true); builder.writeln("项目交付确认单"); builder.getParagraphFormat().setAlignment(ParagraphAlignment.LEFT); builder.getFont().setSize(12); builder.getFont().setBold(false); builder.getParagraphFormat().setFirstLineIndent(24); builder.writeln("本确认单由系统自动生成，请核对后签字确认。"); doc.save(outputPath, SaveFormat.DOCX); doc.cleanup(); // 清理未使用的样式和资源 }

DocumentBuilder的思路是“往光标位置写东西”，写完自动后移。做模板填充时非常好用——你可以moveToBookmark把光标跳到书签位置再写，这比手动定位段落对象清爽得多。

跑通这一步之后，先别急着做业务。建议花半小时做一件事：把生成的 docx 用 Word 打开、用 WPS 打开、用 LibreOffice 打开，三个都看一遍。差异往往在这一步就暴露出来了——特别是字体回退和行距计算，不同渲染器的表现不一样。

4. 真实业务场景实战：合同模板批量生成

这一章是全篇的核心，用一个“合同模板批量生成”的场景把主要能力串起来。这个场景的典型需求是：法务给一份带占位符的 docx 模板，业务系统传入客户信息，输出一份可直接打印签署的 PDF 和一份可归档的 docx。

4.1 占位符替换与富文本回填

最朴素的做法是String.replace，但它有个致命问题：占位符在 Word 里经常被拆成多个 run。什么意思呢？用户在 Word 里输入${customerName}的时候，如果中间不小心切换过输入法、改过格式、或者用过拼写检查，Word 就会把这段文字拆成${customer+Name}两个甚至多个 run，XML 上是分开的节点。你直接对整段文本 replace，匹配不到。

商业库的replace方法内部做了 run 合并，能处理这种情况。Spire.Doc：

public void fillTemplate(Document doc, Map<String, String> data) { data.forEach((key, value) -> { // 第二个参数 false：区分大小写；第三个参数 true：整词匹配 doc.replace("${" + key + "}", value == null ? "" : value, false, true); }); }

Aspose.Words：

public void fillTemplate(Document doc, Map<String, String> data) { FindReplaceOptions options = new FindReplaceOptions(); options.setMatchCase(false); options.setDirection(FindReplaceDirection.FORWARD); data.forEach((key, value) -> { doc.getRange().replace("${" + key + "}", value == null ? "" : value, options); }); }

如果你用 POI 做同样的事，就得自己写一个“跨 run 合并匹配”的工具方法，逻辑大概是：遍历段落的所有 run，拼成一个完整字符串，在完整串上做正则匹配，找到命中的位置后反算出落在哪些 run 上，然后把值塞进第一个命中的 run、把其余 run 中重叠的部分清空。这套逻辑写起来不难但很琐碎，边界情况（比如占位符正好跨越换行、跨越表格单元格）会把人搞疯。

实操心得：模板设计阶段就要定死规矩——占位符必须单独成段或者单独成 run，不要让它在 Word 里被拆开。最好的办法是先用记事本写好占位符再粘进 Word，粘完不要二次编辑。这条规矩能省掉后面 80% 的诡异 bug。

4.2 动态表格行与嵌套循环

合同里最常见的动态结构是“商品明细表”，行数不固定。做法是先在模板里放一行“示例行”，用特殊标记标出要循环的区域，代码里复制这一行再逐行填值。

Spire.Doc 的思路是拿到表格对象，克隆行，插入到指定位置：

public void fillDetailTable(Document doc, List<Item> items) { Section section = doc.getSections().get(0); Table table = (Table) section.getTables().get(0); // 假设第 0 行是表头，第 1 行是模板行 TableRow templateRow = table.getRows().get(1); int insertIndex = 2; for (Item item : items) { TableRow newRow = (TableRow) templateRow.deepClone(); // 单元格索引：0 序号 / 1 名称 / 2 数量 / 3 单价 / 4 金额 newRow.getCells().get(0).getParagraphs().get(0).setText(String.valueOf(item.getSeq())); newRow.getCells().get(1).getParagraphs().get(0).setText(item.getName()); newRow.getCells().get(2).getParagraphs().get(0).setText(String.valueOf(item.getQty())); newRow.getCells().get(3).getParagraphs().get(0).setText(item.getPrice().toPlainString()); newRow.getCells().get(4).getParagraphs().get(0).setText(item.getAmount().toPlainString()); table.getRows().insert(insertIndex++, newRow); } // 删掉原模板行 table.getRows().remove(templateRow); }

这里有三个必须注意的点，每一条我都踩过：

第一，金额一定要用BigDecimal并且显式控制精度。用double算金额再toString，你会看到1234.5600000000001这种结果被写进合同，这是能让人丢工作的错误。统一用setScale(2, RoundingMode.HALF_UP).toPlainString()。

第二，模板行要深拷贝而不是引用。deepClone之后的新对象是独立的，直接 insert 同一个对象引用会导致后面所有行都指向同一份数据，最后所有行显示的内容一模一样。这个 bug 很经典，表现是“明明循环了 5 次，输出 5 行一样的数据”。

第三，删除原模板行的顺序要在插入之后。先删再插入的话索引会错位，容易删掉表头或者越界。

Aspose.Words 里对应的是Row.deepClone(true)配合table.insertBefore，逻辑一致，但要注意它有一个cloneRow相关的邮件合并能力，如果模板设计得好，直接用邮件合并比手写循环简洁得多。

关于跨页表格表头重复：这个属性在 Word 里叫“重复标题行”，程序里设置的方式是给表头行设置RowFormat.HeadingFormat = true（Aspose）或者row.isHeader(true)（Spire）。忘了设的话，几十行的明细表跨页后第二页没有表头，客户会直接打回来。

4.3 图片、页眉页脚与骑缝章位

图片处理有两个坑：尺寸和格式。

尺寸方面，商业库插入图片时默认按原始像素尺寸铺开，一张 4000×3000 的手机照片插进去会把整个版面撑爆。必须显式指定宽高，而且要注意宽高比——只设宽度不设高度，有的库会按比例缩放，有的会拉伸变形。稳妥做法是自己算：

// 按目标宽度等比缩放 int targetWidth = 120; // 单位：point，1 point ≈ 1/72 英寸 BufferedImage bi = ImageIO.read(new File(imagePath)); int targetHeight = (int) Math.round(targetWidth * (double) bi.getHeight() / bi.getWidth()); builder.insertImage(imagePath, targetWidth, targetHeight);

格式方面，EMF、WMF 这类矢量图在 Linux 环境下经常渲染失败，建议统一转成 PNG 再插入。另外插入前最好做一次尺寸压缩——一份合同里塞 20 张 5MB 的原图，生成的 docx 能有 100MB，转 PDF 时内存直接翻倍。

页眉页脚方面，常见需求是“首页不同”“奇偶页不同”“页脚显示第 X 页共 Y 页”。页码的实现依赖域代码（Field），这里有个关键动作：插入域之后必须更新域，否则 PDF 里显示的是空或者旧值。

// Aspose.Words：更新所有域 doc.updateFields();

Spire.Doc 的做法类似，但要调用doc.updatePageLayout()再刷新。页码总数NUMPAGES域尤其要注意，它在转 PDF 之前是算不出来的，必须在转 PDF 之后才有正确值——所以有些团队的做法是“先转 PDF，再在 PDF 上盖章页码”，反而更稳。

4.4 Word 转 PDF 与字体铺平

这一步是整个链路里最容易翻车的地方，而翻车原因 90% 是字体。

现象是这样的：本地 Windows 开发机上跑得好好的，一上 Linux 容器，中文全部变成方块或者变成宋体以外的默认字体，行距也变了，本来 3 页的文档变成 4 页，最后一页只剩两行。

根本原因是：PDF 转换需要真实的字体文件来做字形度量，而 Linux 基础镜像里通常只有 DejaVu 这类西文字体，没有中文字体。库找不到字体，就会做一次“字体回退”，回退到哪个不确定，度量也不对，版式自然崩。

解决办法是把中文字体装进镜像并显式注册。以 Aspose 为例：

@PostConstruct public void initFonts() { // 把项目自带的开源中文字体目录注册进去 FontSettings.getDefaultInstance().setFontsFolder("/opt/app/fonts", true); // 找不到字体时不要静默回退，直接抛出来 FontSettings.getDefaultInstance().setFontSubstitutionRule(null); }

Spire.Doc 的做法是通过Document.setFontSettings或者FontSettings.setFontsFolder指定目录。

字体来源要合规，推荐用开源字体或者有授权的商业字体，不要直接从 Windows 系统目录里拷字体文件塞进容器——那是另一个授权问题。实际项目里常见的组合是：标题用开源的黑体类字体，正文用开源的宋体类字体，然后在前端预览的时候用同一套字体，保证所见即所得。

转 PDF 的核心代码很简短：

// Aspose doc.save(outputPdfPath, SaveFormat.PDF); // Spire doc.saveToFile(outputPdfPath, FileFormat.PDF);

代码简单，但工程上要做的事情不少：转换前要校验文档没有损坏、转换要设超时（遇到过畸形模板导致转换卡死十分钟的情况）、转换后要校验 PDF 页数是否符合预期（页数突变说明版式崩了）、失败要有降级策略。

提示：生产环境建议对“转 PDF”这一步做一次结果校验——用 PDFBox 打开输出文件读页数，和预期页数比对，超过阈值就告警。这个简单的检查帮我们提前发现了三次模板变更导致的版式问题。

5. 上线之后才会遇到的问题排查实录

本地跑通和线上稳定之间隔着一条鸿沟。这一章挑几个最有代表性的问题讲。

5.1 中文乱码与字体缺失

除了上面说的容器字体问题，还有一种更隐蔽的情况：字体名称映射失败。

模板里写的字体名可能是“宋体”或者“SimSun”，如果你注册的字体文件内部名称是别的（比如某些开源字体内部名是英文的 Noto Serif CJK SC），库按名字找不到，就回退。表现是“字体没变成方块，但明显不是宋体”，而且行距、字宽都有细微差异，导致分页位置偏移。

排查方法：用fc-list命令把容器内所有字体的族名列出来，和模板里用到的字体名逐个比对。缺哪个补哪个，或者做一层名称映射，把“宋体”映射到实际注册的字体族名。

还有一个反直觉的点：字体文件加载是有内存开销的。一次性注册几百个字体文件，JVM 启动会慢好几秒，内存也涨。实际项目里只装需要的那几个字重就够了，别把整个字体库塞进去。

5.2 内存持续上涨与对象释放

这个问题我必须重点讲，因为它最有欺骗性。

现象：服务跑一天没事，跑三天后容器被 OOMKilled。看监控，堆内存平稳，GC 正常，但容器实际内存一路涨。抓堆 dump 分析，找不到大对象。

原因：商业文档库在 JVM 堆外分配了原生内存（用于字体缓存、图像解码、排版中间结果）。这部分内存不受 JVM 参数控制，只能靠库自己的释放机制回收。Document对象如果不显式调用dispose()或cleanup()，关联的原生内存就一直挂着，等 GC 触发finalizer或者Cleaner才回收——而这个时机完全不可控。

解决办法有三条，我建议全做：

一是所有Document必须放在 try-finally 里释放，这个是硬规矩，Code Review 时当红线卡。

二是限制单次处理的文档大小。一个 200 页含 500 张图片的文档，转 PDF 时原生内存可能吃到几个 G。业务上要设上限，超了直接拒绝并提示用户拆分。

三是给容器设内存上限并留足余量。容器 limit 是 4G 的话，堆内存最多设 2G，剩下 2G 留给原生内存。堆设太大反而会挤压原生内存空间，导致更早被 kill。

5.3 并发场景下的线程安全

两个明确结论：

第一，Document对象不是线程安全的。同一个实例不能在多线程里同时读写。批量场景下，正确做法是每个线程从模板文件重新加载一份独立的Document，处理完销毁。不要试图用一个模板对象 clone 出多个来省 IO——clone 本身也涉及内部状态复制，且克隆出来的对象共享部分底层资源，容易出诡异问题。

第二，授权凭证是全局的，只需设置一次。放在静态初始化块或者@PostConstruct里，不要在请求线程里重复设置。

并发度怎么定？我的经验值是：转 PDF 这类 CPU 密集型任务，并发度设成 CPU 核数的 1 到 1.5 倍，再高没有收益，反而因为内存竞争导致吞吐下降。生成 docx 这类相对轻的任务可以设到 2 倍。更稳的做法是加一个信号量限流，避免突发流量把原生内存打爆。

5.4 常见问题速查表

这张表建议直接抄进团队 wiki。文档处理模块的问题有很强的重复性，大部分新问题都能在历史记录里找到影子。

6. 成本、锁定与长期维护

最后聊点务实的。技术选型不只是“能不能实现”，还包括“五年后还改不改得动”。

6.1 算一笔账：买授权、换开源、自研

商业授权的计价方式通常是按开发者席位 + 部署实例，团队规模大、部署环境多（开发/测试/预发/生产）的时候，费用会明显上升。有些厂商对 SaaS 场景有单独的计价方式，采购前一定要把“我们的产品形态”跟销售讲清楚，否则后面可能被要求补差价。

把三个选项摆在一起算：

我个人的判断标准是：如果这个文档模块的开发人力成本超过了授权费的 1.5 倍，就买。这个比例不是拍脑袋，是把“开发和调试时间”“后续每年的维护时间”“出事故的损失”折算进去之后得出的。很多团队只算了第一个，忽略了后两个。

另外提醒一句：采购时要确认升级权益。文档格式在演进，今年能正确解析的模板，明年未必。如果没有升级权益，你会在某次 Office 更新后发现一批模板突然渲染错乱，而升级要另外付钱。

6.2 用一层薄封装隔离厂商锁定

不管选了哪个库，都强烈建议在业务代码和库之间加一层自己的抽象。这不是过度设计，是保命。

具体做法是定义一个接口，把“模板填充”“表格生成”“转 PDF”这些能力抽象出来，实现类里才调具体的库：

public interface WordDocumentService { /** 基于模板填充数据，返回 docx 字节流 */ byte[] fillTemplate(InputStream template, Map<String, Object> data); /** 把 docx 转成 PDF */ byte[] convertToPdf(InputStream docx); /** 给文档加水印 */ byte[] addWatermark(InputStream docx, String text); }

好处有三个：一是将来换库只需要改一个实现类；二是测试的时候可以轻松 mock；三是能把“哪个库能做哪件事”的能力差异收敛在实现层，不污染业务逻辑。

封装的时候有个细节要注意：不要把库的异常类型透出去。定义自己的业务异常，把库的异常包装进去，日志里保留原始堆栈，给上游只暴露“文档生成失败”这种语义化信息。否则某天换库，所有 catch 块都得改一遍。

另外，模板文件本身也要做版本管理。建议把模板纳入代码仓库或者专门的配置中心，每次改动走审核流程，并且保存一份“模板变更记录”。我们踩过的坑是：法务改了模板里的一个占位符名字，没有任何通知，上线后批量生成全部失败，排查了两小时才发现是模板变了。现在我们的规矩是模板改动必须走工单，改完自动跑一遍回归用例。

我在实际操作中的体会是：文档处理这个领域，最贵的从来不是那个 jar 包，而是你对模板、字体、版式的掌控程度。库只是放大器——模板设计得干净，开源库也能跑得很稳；模板一团乱麻，再贵的商业库也只能救你一半。所以真正值得投入时间的地方，是建立一套“模板规范 + 回归用例 + 输出校验”的机制，让每次生成的文档都可预期。至于用哪个库，等你把规范和用例建起来之后，答案基本就自己浮出来了。