简介这份资源面向 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 标记的 jarAspose.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 里要同时加仓库和 dependencyrepositories repository idaspose-repo/id urlhttps://repository.aspose.com/repo//url /repository /repositories dependencies dependency groupIdcom.aspose/groupId artifactIdaspose-words/artifactId version21.11/version classifierjdk17/classifier /dependency /dependenciesclassifier是这里的关键字段。Maven 用它区分同一个groupId:artifactId:version下的不同构建物不写的话默认拉回不带 classifier 的 JDK 11 版本。JDK 17 项目短时间可能不报错但一旦触发模块强封装相关的类路径行为就和预期不一致了。内网环境访问不了外部仓库时把 jar 放到项目的 libs 目录用 system scope 引dependency groupIdcom.aspose/groupId artifactIdaspose-words/artifactId version21.11/version classifierjdk17/classifier scopesystem/scope systemPath${project.basedir}/libs/aspose-words-21.11-jdk17.jar/systemPath /dependencysystem scope 的坑是打包容易漏。用 Spring Boot 的 Maven 插件时要在configuration里显式开启includeSystemScope否则打出来的 fat jar 里找不到这个依赖部署环境一启动就ClassNotFoundException。如果团队有本地仓库更省事的做法是用 install-file 装进去mvn install:install-file \ -Dfilelibs/aspose-words-21.11-jdk17.jar \ -DgroupIdcom.aspose \ -DartifactIdaspose-words \ -Dversion21.11 \ -Dclassifierjdk17 \ -Dpackagingjar这个命令会把 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读出来写到临时目录再传给setLicensetry (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);参数含义和影响范围见下表参数默认行为建议值影响面CompliancePDF 1.5PDF_A_1_B存档合规强制字体嵌入TextCompressionFLATEFLATE文本层压缩体积影响大ImageCompressionAUTOAUTO自动选择图片编码方式JpegQuality9585-90有损图像质量与体积的平衡ExportDocumentStructurefalsetrue生成 PDF 标签树无障碍阅读DownsampleOptions220dpi150dpi图片降采样体积可小一半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 (StreamPath 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实现了AutoCloseabletry-with-resources 会在save结束后释放内部排版缓冲区。批量场景最常见的翻车点是手动new Document之后忘了 close靠 GC 只能回收堆对象排版引擎的堆外资源回收不掉跑一段时间内存就顶不住。pdfOptions在循环里复用是安全的转换过程不会修改它的内部状态。loadOptions同样可以复用但FontSettings建议保持在LoadOptions里而不是 set 到全局静态避免多线程并发时字体解析相互干扰。4. 转换避坑实录五个高频翻车点这些坑不是某个特定环境独有的是 Aspose.Words 在服务端跑起来之后几乎每家团队都要过一遍的。有些问题第一次遇到确实玄学——同一个 jar 在本地转得好好的部署到容器里就全变方块本地演示没水印客户环境一跑水印就出来。逐条拆开看原因都写在配置里。4.1 中文全部变成空心方块现象转换出的 PDF 文字全部是空心的方框英文正常中文全部错位。原因服务器缺少中文字体。Word 文档里写的字体名是宋体服务端字体目录里没有这个字体或没有可回退的中文字体排版引擎 fallback 失败后只能画占位框。解决先确认服务器上有哪些中文字体fc-list :langzh如果为空安装 Noto Sans CJKapt-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.jartempFolder的本质是让排版引擎把一部分缓存写到磁盘用磁盘空间换内存上限。注意临时目录的磁盘要有足够余量至少和源文件同等大小。我踩过这个坑源文件 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 里也跑一道保证每次调完参数没有回归。文档转换这种看起来简单的功能恰恰是改了参数就容易翻车的地方。把这套验证做成脚本固定下来后面所有结构调整都有底气。希望帮到你。本文还有配套的精品资源点击获取