企业官网建设流程全解析

简介：这份资源面向 Java 开发者，提供 aspose-words 21.11 针对 JDK 17 的 Word 转 PDF 解决方案。压缩包内共 2 个文件：一个 aspose-words-21.11-jdk17.jar 核心库，以及一个 PDFHelper.java 示例，演示如何引入依赖、设置许可证并执行转换。包体仅 13.7MB，轻量易用，可直接复制到项目 resources/lib 目录下完成本地集成。示例方法中已包含 License 配置逻辑，可帮助避开转换水印与评估警告等常见问题。目前已有 706 人学习下载，适用于需要快速实现 Word 导出 PDF 功能的 Java Web 或桌面项目，尤其适合使用 JDK 17 的 Spring Boot 工程。通过学习示例，开发者能省去查阅官方文档与调试 ClassNotFound 等依赖冲突的时间，直接套用转换逻辑，并了解 systemPath 方式引入本地 jar 的 Maven 配置要点。

1. 拿到 aspose-words-21.11-jdk17.jar 之后：先把 Word 转 PDF 跑通的正确姿势

项目从 JDK 11 升级到 JDK 17 之后，原来那套文档转换方案直接起不来，编译不报错，运行时报模块访问错误，查了一圈是依赖库对 JDK 17 的强封装机制没适配。换过开源方案，要么样式还原度不够，要么中文乱码，兜兜转转还是用 aspose-words-21.11-jdk17.jar 把主流程跑通了。这个 jar 是 Aspose.Words 专门为 JDK 17 编译的构建，三行代码就能把 docx 转成 PDF，页面布局基本不用大调。但它的坑不在 API，而在 API 之外：许可证初始化、服务端字体目录、PDF 合规级别这三样配置不对，转出来的 PDF 要么带水印，要么中文全是空心方块。这篇笔记把这些点逐个拆开，给出可以直接抄的代码和参数表。

2. 先搞清楚 21.11 这个版本：jdk17 classifier 解决的是模块兼容问题

在写转换代码之前，先把 jar 的来龙去脉理一遍。很多人在 JDK 17 下遇到的第一个报错是java.base does not export sun.*这一类，这类报错跟业务逻辑无关，纯粹是依赖库的模块描述符没有适配新 JDK。

2.1 为什么要用带 jdk17 标记的 jar

Aspose.Words 21.11 在发布时针对 JDK 17 单独提供了构建产物。同一个版本号下，带jdk17classifier 的 jar 是按 JDK 17 编译的，模块描述符的处理方式和默认构建不同。拿错构建最典型的现象是：编译期一切正常，运行期抛IllegalAccessError，而且报错位置在转换引擎内部，跟你的业务代码没有直接关系。

拿到 jar 先验证包结构：

jar tf aspose-words-21.11-jdk17.jar | grep 'com/aspose/words/Document.class'

能查到Document.class只是第一步。更可靠的方式是把它引入项目，写一段包含Document doc = new Document("x.docx")的最小代码跑一遍，能正常执行就说明和当前 JDK 匹配。我们团队内部就遇到过两次：一次是拿错成 jdk11 构建，一次是从网盘下载的压缩包被重命名过，实际内容是旧版本，用这种执行验证法半小时内就能定位。

2.2 Maven 依赖和离线引法

项目用 Maven 管理依赖时，pom 里要同时加仓库和 dependency：

<repositories> <repository> <id>aspose-repo</id> <url>https://repository.aspose.com/repo/</url> </repository> </repositories> <dependencies> <dependency> <groupId>com.aspose</groupId> <artifactId>aspose-words</artifactId> <version>21.11</version> <classifier>jdk17</classifier> </dependency> </dependencies>

classifier是这里的关键字段。Maven 用它区分同一个groupId:artifactId:version下的不同构建物，不写的话默认拉回不带 classifier 的 JDK 11 版本。JDK 17 项目短时间可能不报错，但一旦触发模块强封装相关的类路径，行为就和预期不一致了。

内网环境访问不了外部仓库时，把 jar 放到项目的 libs 目录，用 system scope 引：

<dependency> <groupId>com.aspose</groupId> <artifactId>aspose-words</artifactId> <version>21.11</version> <classifier>jdk17</classifier> <scope>system</scope> <systemPath>${project.basedir}/libs/aspose-words-21.11-jdk17.jar</systemPath> </dependency>

system scope 的坑是打包容易漏。用 Spring Boot 的 Maven 插件时，要在configuration里显式开启includeSystemScope，否则打出来的 fat jar 里找不到这个依赖，部署环境一启动就ClassNotFoundException。如果团队有本地仓库，更省事的做法是用 install-file 装进去：

mvn install:install-file \ -Dfile=libs/aspose-words-21.11-jdk17.jar \ -DgroupId=com.aspose \ -DartifactId=aspose-words \ -Dversion=21.11 \ -Dclassifier=jdk17 \ -Dpackaging=jar

这个命令会把 jar 装进本地 Maven 仓库，之后 pom 里照常依赖，不需要 systemPath。要注意 install-file 只对当前机器生效，需要让团队其他成员也拿到，需要走私有仓库的 deploy-file。

2.3 License 初始化：不解决水印问题后面全白做

Aspose 系列库不是免费商用，没有许可证时转换结果会在页面角落打出灰色水印，文档长度也会被截断，试用模式只处理前几页。初始化方式固定，建议放在静态块里：

import com.aspose.words.License; public class LicenseInit { private static final License LICENSE = new License(); static { try { LICENSE.setLicense("aspose-words.lic"); } catch (Exception e) { throw new ExceptionInInitializerError(e); } } }

setLicense只需要调用一次，进程内所有Document实例共享许可证状态。注意它必须在第一次new Document之前执行，否则这次运行期间的所有转换都会带水印。

注意：setLicense 必须在首次创建 Document 实例之前调用，否则当前进程内的转换结果会一直带水印。

另一个隐蔽问题：程序打成 fat jar 后许可证文件读不到。setLicense接收的是文件路径，不会自动扫 classpath。遇到这种情况，把.lic文件放进src/main/resources，在代码里用getResourceAsStream读出来写到临时目录，再传给setLicense：

try (InputStream is = LicenseInit.class.getResourceAsStream("/aspose-words.lic")) { if (is == null) { throw new IllegalStateException("license not found in classpath"); } Path tmp = Paths.get(System.getProperty("java.io.tmpdir"), "aspose-words.lic"); Files.write(tmp, is.readAllBytes(), StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING); LICENSE.setLicense(tmp.toString()); }

这段逻辑处理的是 jar 包里资源无法直接当文件路径传给原生库的场景，先落地到临时目录再调用，兼容性最高。

2.4 最小转换程序：跑通再谈优化

import com.aspose.words.Document; import com.aspose.words.SaveFormat; public class WordToPdfDemo { public static void main(String[] args) throws Exception { Document doc = new Document("input.docx"); doc.save("output.pdf", SaveFormat.PDF); } }

new Document阶段会把 docx 的 OOXML 包解析成内存里的文档对象模型，文件里引用的样式表、主题、字体表在这一步构建；save阶段是真正的排版渲染，逐页计算布局后输出 PDF。复杂文档的耗时基本都花在 save 上。

转换完建议顺手验证页数：

System.out.println("pages: " + doc.getPageCount());

getPageCount()会触发一次完整排版，注意要在save之前调用，否则白白多排一次版。若能正常输出页数且水印不出现，说明 jar、许可证、JDK 环境这套底座已经通了，接下来才是调参数。

3. 转换质量的差别全在参数：LoadOptions 和 PdfSaveOptions 的必调项

最小示例只是打通流程。实际生产里，不同来源的 Word 文档对应不同的加载策略，文档本身千差万别，同一个转换参数很难通吃。这一章把加载和输出两个环节的可调参数拆开讲。

3.1 加载 Word 文档的三个常用选项

import com.aspose.words.*; LoadOptions options = new LoadOptions(); options.setPassword("your-password"); options.setTempFolder("/data/tmp/word2pdf"); options.setFontSettings(FontSettings.getDefaultInstance()); Document doc = new Document("input.docx", options);

setPassword处理带打开密码的 docx，没密码的文档传不传都不影响。setTempFolder把排版中间数据写到磁盘，能显著降低大文档的内存峰值，代价是转换速度变慢，适合几百 MB 级别的文件。setFontSettings指定字体解析策略，默认实现会扫描系统全部字体目录，这对转换质量的影响最大。

字体这块是最容易踩坑的。服务端是精简容器时，里面往往一个中文字体都没有，转换出来的 PDF 中文全是空框。手动指定字体目录更可靠：

FontSettings fs = new FontSettings(); fs.setFontsFolder("/usr/share/fonts/opentype/noto", true); options.setFontSettings(fs);

第二个参数true表示递归扫描子目录。生产服务器上至少要有宋体、黑体或者 Noto Sans CJK 一类的中文字体，否则 Word 里指定的"宋体"在字体回退时失败，排版也会跟着错位。

3.2 PdfSaveOptions 里决定成品质量的六个参数

PdfSaveOptions pdf = new PdfSaveOptions(); pdf.setCompliance(PdfCompliance.PDF_A_1_B); pdf.setTextCompression(PdfTextCompression.FLATE); pdf.setImageCompression(PdfImageCompression.AUTO); pdf.setJpegQuality(90); pdf.setExportDocumentStructure(true); DownsampleOptions ds = new DownsampleOptions(); ds.setDownsampleImages(true); ds.setResolution(150); pdf.setDownsampleOptions(ds);

参数含义和影响范围见下表：

Compliance是档案系统和数字签章最关心的参数。PDF_A_1_B是 PDF/A-1b 合规格式，对字体嵌入、颜色空间、透明度对象都有强制要求，很多政务平台上传材料只认这种格式。如果只是内部打印，保持默认 PDF 1.5 反而转换更快、文件更小。

DownsampleOptions的Resolution会把超过阈值的图片降采样。默认 220dpi 对屏幕阅读足够了，调成 150dpi 肉眼基本察觉不到差别，几十页带扫描件的文档体积能缩减一半。JpegQuality只对 JPEG 编码的图片生效，纯文本文档基本不受影响。

3.3 批量转换和内存回收

生产环境很少只转一个文件，批量场景更考验代码习惯：

Path inputDir = Paths.get("/data/docx"); Path outputDir = Paths.get("/data/pdf"); Files.createDirectories(outputDir); try (Stream<Path> paths = Files.walk(inputDir)) { paths.filter(p -> p.toString().endsWith(".docx")) .forEach(p -> { String out = outputDir.resolve(p.getFileName().toString().replace(".docx", ".pdf")).toString(); try (Document doc = new Document(p.toString(), loadOptions)) { doc.save(out, pdfOptions); System.out.println("converted: " + p.getFileName()); } catch (Exception e) { System.err.println("failed: " + p + " -> " + e.getMessage()); } }); }

Document实现了AutoCloseable，try-with-resources 会在save结束后释放内部排版缓冲区。批量场景最常见的翻车点是手动new Document之后忘了 close，靠 GC 只能回收堆对象，排版引擎的堆外资源回收不掉，跑一段时间内存就顶不住。

pdfOptions在循环里复用是安全的，转换过程不会修改它的内部状态。loadOptions同样可以复用，但FontSettings建议保持在LoadOptions里，而不是 set 到全局静态，避免多线程并发时字体解析相互干扰。

4. 转换避坑实录：五个高频翻车点

这些坑不是某个特定环境独有的，是 Aspose.Words 在服务端跑起来之后几乎每家团队都要过一遍的。有些问题第一次遇到确实玄学——同一个 jar 在本地转得好好的，部署到容器里就全变方块；本地演示没水印，客户环境一跑水印就出来。逐条拆开看，原因都写在配置里。

4.1 中文全部变成空心方块

现象：转换出的 PDF 文字全部是空心的方框，英文正常，中文全部错位。

原因：服务器缺少中文字体。Word 文档里写的字体名是"宋体"，服务端字体目录里没有这个字体或没有可回退的中文字体，排版引擎 fallback 失败后只能画占位框。

解决：先确认服务器上有哪些中文字体：

fc-list :lang=zh

如果为空，安装 Noto Sans CJK：

apt-get install fonts-noto-cjk

然后在代码里显式指定字体目录：

FontSettings fs = new FontSettings(); fs.setFontsFolder("/usr/share/fonts", true); LoadOptions lo = new LoadOptions(); lo.setFontSettings(fs); Document doc = new Document("input.docx", lo);

注意FontSettings必须在new Document之前关联到LoadOptions，否则转换时会重新走系统字体扫描，问题依旧。

4.2 许可证水印还在，文档被截断

现象：转换后页面上有灰色 Evaluation 水印，而且输出 PDF 少了几页。

原因：许可证初始化没执行，或者setLicense抛异常被吞了。另一个容易被忽略的场景：在多个类里引用了不同的License实例，setLicense必须在首次创建Document之前执行。

解决：在 main 方法第一行或容器启动入口做许可证初始化，异常不要吞：

License lic = new License(); try { lic.setLicense("/opt/lic/aspose-words.lic"); } catch (Exception e) { throw new IllegalStateException("Aspose license invalid", e); }

如果许可证路径确认无误仍报 Evaluation，检查密钥和 jar 版本的匹配关系，21.11 的许可证和后续大版本的密钥并不通用。

4.3 宽表格被截断

现象：模板里设计为 A4 横版的表格，转成 PDF 后右侧一部分列跑到页面外。

原因：页面尺寸是 A4 纵向，原表格是按横版宽度设计的。Word 里会自动缩放显示，但 Aspose.Words 渲染 PDF 时严格按 section 的页面设置输出，不会自动缩表格。

解决：转换前设置表格允许自动调整：

Table table = (Table) doc.getChild(NodeType.TABLE, 0, true); table.setAllowAutoFit(true);

也可以在 Document 层面把 section 的方向改为横向：

for (Section section : doc.getSections()) { section.getPageSetup().setOrientation(Orientation.LANDSCAPE); }

我一般先让 Word 里的表格原始宽度适配 A4 可打印区，再处理方向问题。改完记得用getPageCount()验证页数变化，页数明显增加说明有内容被挤到新页，需要人工看一下。

4.4 转换耗时长到怀疑人生

现象：一百页的文档转 PDF 耗时两分多钟，线上接口的延迟根本压不住。

原因：一是图片没有降采样，原文档里的 300dpi 扫描图原样嵌入 PDF；二是每次转换都new FontSettings()，重复扫描所有字体文件，这个开销在高并发场景被无限放大。

解决：复用 FontSettings 实例：

private static final FontSettings FONT_SETTINGS; static { FONT_SETTINGS = new FontSettings(); FONT_SETTINGS.setFontsFolder("/usr/share/fonts", true); }

降采样参数同步调整：

PdfSaveOptions pdf = new PdfSaveOptions(); DownsampleOptions ds = new DownsampleOptions(); ds.setDownsampleImages(true); ds.setResolution(120); pdf.setDownsampleOptions(ds);

FontSettings初始化一次之后静态持有，整个进程复用。降采样到 120dpi 对屏幕阅读足够，打印会有轻微损失，内部材料可以接受。

4.5 大文档内存溢出

现象：堆内存 2GB，转一个 200MB 的 docx 时报 OOM。

原因：Document模型会把整个文档对象树加载到内存，save 排版时还需要额外的缓冲区，高峰期内存占用是源文件体积的 5 到 10 倍。

解决：给LoadOptions设置临时文件夹：

LoadOptions lo = new LoadOptions(); lo.setTempFolder("/data/word-tmp"); Document doc = new Document("large.docx", lo);

JVM 参数按需提高上限：

java -Xms512m -Xmx4g -jar converter.jar

tempFolder的本质是让排版引擎把一部分缓存写到磁盘，用磁盘空间换内存上限。注意临时目录的磁盘要有足够余量，至少和源文件同等大小。我踩过这个坑，源文件 200MB 时临时目录峰值大约 1.8GB，磁盘满了会直接报 IO 异常，错误信息还不太明显。

5. 转完了怎么验：文本抽取、页数对比和 PDF/A 合规检查

转换完心里不踏实，说明缺一个验证闭环。我一般做三层检查。

第一层看页数和文本完整性。用 Apache PDFBox 抽取 PDF 文本：

import org.apache.pdfbox.pdmodel.PDDocument; import org.apache.pdfbox.text.PDFTextStripper; PDDocument pdf = PDDocument.load(new File("output.pdf")); PDFTextStripper stripper = new PDFTextStripper(); String pdfText = stripper.getText(pdf);

把 Word 原文里的关键段落和 PDF 抽取结果做包含关系断言，能抓到大部分内容丢失的问题。页数对比用doc.getPageCount()和pdf.getNumberOfPages()，偏差超过一页就说明排版有变化。

第二层查 PDF/A 合规。设了PDF_A_1_B之后，用合规性验证器检查输出文件，主要拦截三件事：字体未嵌入、透明对象未平面化、色彩空间不符合。合规检查一旦报错，回去看Compliance设置和字体嵌入相关配置。

第三层做关键页快照。把 PDF 按页渲染成 PNG，人工确认目录页、带复杂表格的页、含大图的页没有错位。这一步最花时间，但对最终交付的把握最大。

我自己的习惯是，在转换工具里保留一个verify参数，本地开发跑的时候带着，CI 里也跑一道，保证每次调完参数没有回归。文档转换这种看起来简单的功能，恰恰是改了参数就容易翻车的地方。把这套验证做成脚本固定下来，后面所有结构调整都有底气。希望帮到你。

本文还有配套的精品资源，点击获取