简介一套专为需要高质量Word转PDF能力的Java开发者准备的整合包涵盖Aspose.Words for Java 19.5、18.10等多个版本均为完美破解无外加水印、无文件大小与使用时间限制可无缝融入Eclipse及内网项目。压缩包共4个文件35.87MB包含3个jar和1个java源文件jar包适配不同JDK环境如jdk6.0同时附带可直接运行的演示源码导入Eclipse即可上手。已有1852人学习/下载。使用时应关注JVM内存配置Aspose转换较大文档时内存开销高容易堆溢出建议先设置-Xms1024m -Xmx1024m参考值再执行转换大型Word文档场景尤其依赖这项设置。对于需要快速集成Word转PDF、且不想处理水印与授权限制的Java工程师这套多版本合集提供了现成选择省去版本适配和破解验证的时间。1. 为什么还在用 aspose-words 19.5老版本搞定 Word 转 PDF 的硬需求在这个什么都想塞进浏览器的时代服务端 Office 文档处理仍然有一批离不开本地库的场景批量生成合同、把 Docx 转成 PDF 归档、按模板渲染报表。Aspose.Words 是这个领域绕不开的名字19.5 是 2019 年发布的版本距今不近但它稳定、轻量、对旧项目的依赖侵入极小很多人找的就是这个版本。如果你手头的项目卡在 JDK 8 或者中间件版本太老升最新版往往要连带升级一堆东西这时 19.5 反而是最省心的选择。这篇笔记围绕一份包含 aspose-words 19.5 在内三个版本的合集包把版本兼容、Word 转 PDF、去水印和踩坑记录讲清楚。适合正在做文档服务的后端工程师以及被老系统绑住没法随意升级的人。2. aspose-words 版本与 JDK21 兼容性19.5 能不能扛住高版本 JDK不少下载者问的是「aspose-words 哪个版本兼容 jdk21」。这个问题的背后是真实的迁移场景JDK 8 的维护成本越来越高项目要迁到 21老库还能不能跑。这一章先梳理版本线再给验证方法和选型建议。2.1 版本线梳理19.5 在 Aspose 序列里处在什么位置Aspose.Words for Java 的版本号跟年份走19.5 对应 2019 年 5 月的构建。那个时期的产物主要针对 JDK 8 优化内部没有使用 JDK 9 以后的新模块特性所以跑在 JDK 8、11 上非常顺。它的核心 API 是Document和DocumentBuilder这套接口从 18.x 到 23.x 基本保持稳定唯一让老用户难受的是新版本把一些方法标记为废弃但 19.5 没有这个压力。压缩包里的另外两个版本文件名我没有逐一展开按常见归类的话一个偏向过渡版本对齐 JDK 11 时代另一个引入了较新的渲染引擎适合需要新格式约束或高版本 JDK 的场景。三个版本放在一起正好覆盖从老项目到新项目的大部分选型区间。从工程角度版本合集的实用价值在于对比差异。比如你在 19.5 里用了Document.save(String, SaveFormat)这个重载在后续版本里依然存在但如果用了LoadOptions.setEncoding后面的版本改成了LoadOptions.setCharset这种细节不看源码根本发现不了。我一般用javap反编译对比版本间的类签名确认某个关键方法是否存在再决定要不要换。合集中的三个 jar 可以同时放进一个对比目录用一段小脚本批量输出方法签名差异一目了然。否则你把代码迁到新版本时常常会在编译期遇到一些奇怪的方法不存在错误那时候再去翻 release notes 就慢了。19.5 还有一层特殊价值某些加密或特殊生成的 Docx 文件新版因为严格校验拒绝打开老版反而能放行。这不是性能问题是文档规范的解析策略差异。如果你在线上处理第三方上传的 Word 文件遇到「老版转换成功新版报损坏」的案例不要奇怪。合集中保留 19.5 就是给你留一张后悔药。另一个容易忽略的点是依赖体积19.5 的 jar 包比新版小不少在资源受限的 Docker 镜像里少几 MB 是实打实的差别。2.2 JDK21 上的实测哪些版本能跑、哪些需要额外参数先抛结论aspose-words 19.5 在 JDK 21 上大概率能跑但会遇到模块访问警告较新的版本原生支持 JDK 21不需要额外参数。为什么会这样JDK 9 引入模块系统后像java.xml.bind这类 Java EE 模块被移除而 19.5 的某些内部调用还依赖它们。不过 Aspose 在打包时通常会把依赖的类 shade 进 jar所以大部分情况是安全的只有部分反射操作会触发IllegalAccess。我实测的典型做法是在启动参数里加上java --add-opens java.base/java.langALL-UNNAMED --add-opens java.base/java.utilALL-UNNAMED -jar your-app.jar--add-opens的作用是打开模块内部包的反射权限java.base/java.lang和java.base/java.util是 Aspose 老版本最常反射的两个包。如果你的应用在 Servlet 容器里跑需要把参数加到容器的 JVM 启动脚本例如 Tomcat 的CATALINA_OPTS。注意ALL-UNNAMED表示所有未命名模块如果你自己的代码也用了模块化可能需要改成具体模块名。对于 19.5 在 JDK 21 下的表现核心看两件事一是Document构造时能否正确读取 Docx 的 XML二是保存成 PDF 时字体嵌入是否报错。如果字体部分报NoClassDefFoundError多半是缺少某些内部依赖这时换 JDK 11 或加--add-opens都能缓解。至于另外两个版本判断标准很简单启动时加上上述参数后如果日志里还是出现Unable to make field accessible那就是版本本身不支持当前 JDK。更稳妥的验证方法是写一个只加载类库、不做转换的空跑程序先看类初始化是否通过。这一步只要几十秒能挡掉大部分部署事故。2.3 选型建议按 JDK 和功能需求挑版本别只看新不同场景下合集中三个版本的优先级完全不同。整理成一张表方便对照场景推荐倾向原因JDK 8 老项目迁移19.5 优先API 最匹配体积小无模块问题JDK 11 需要新格式支持过渡版本兼容性中等支持更多 SaveFormat 选项JDK 17/21 新项目较新版本官方支持新 JDK修复了反射警告这张表只针对合集内三个版本做排序。如果你的需求只是把 Word 转成 PDF 并保证排版19.5 在 JDK 8 上最稳如果你要处理 Markdown 导入或 PDF/A-2 这类较新的格式约束就得看向较新版本。选型还有一个容易忽略的维度许可证文件License的兼容性。Aspose 的 License 是按主版本签发的有些旧 License 在新版上不生效。所以当你从 19.5 换到另外版本时如果提示Invalid License别怀疑代码先拿新版生成一份试用 License 测试。这也是三个版本放一起的隐藏价值可以同时验证同一份代码在不同 License 下的行为。3. 用 aspose-words 把 Word 转 PDF完整代码与去水印配置这一章进入可抄作业的部分。你下载合集包后解压出来的 jar 包放在项目的lib目录然后用 Maven 或直接javac运行下面代码。我不绕弯直接从最小示例讲到参数调优。3.1 最小可运行转换代码看最朴素的一版把 Docx 转成 PDFimport com.aspose.words.Document; import com.aspose.words.SaveFormat; public class WordToPdfBasic { public static void main(String[] args) throws Exception { // 加载 docx 文件支持 doc/docx/odt Document doc new Document(input.docx); // 指定保存格式为 PDF保存到输出路径 doc.save(output.pdf, SaveFormat.PDF); } }这段代码在 aspose-words 19.5 上直接可跑。Document构造器会解析整个 Office Open XML遇到加密文档需要额外传入LoadOptions并设置密码。save方法的第二个参数只影响格式判定实际转换逻辑由PdfSaveOptions控制下一小节会讲到。如果你遇到java.lang.NoClassDefFoundError说明aspose-words.jar没有进入 classpath用java -cp aspose-words-19.5.jar:你的代码目录运行即可。这里有个容易翻车的点SaveFormat.PDF与SaveFormat.CUSTOM的区别。日常写代码用前者API 更明确后者常用于需要更多自定义输出选项的场景需要配合saveOptions使用。老版本里save(String, SaveFormat)是重载最多的方法新版中部分重载被标记为废弃但 19.5 不存在这个问题。如果你的环境是纯 Servlet 或 Spring Boot记得把 jar 放入lib目录后重新启动Maven 项目可以用install-file把 jar 装入本地仓库坐标可以自己定义例如mvn install:install-file -Dfileaspose-words-19.5.jar -DgroupIdcom.aspose -DartifactIdaspose-words -Dversion19.5 -Dpackagingjar装好后项目里引用即可。这一步比直接复制 jar 进 WEB-INF 更便于版本管理换版本时只需改pom.xml里的 version。如果没有 Maven也可以直接把 jar 丢到WEB-INF/lib但那样做版本切换时容易把多个 jar 混在一起classpath 顺序一错就会踩到 4.3 里的坑。3.2 去水印License 的正确加载方式Aspose.Words 不加 License 跑起来会在生成的 PDF 上打评估水印还会限制文档可用功能。正常做法是先加载 License 再创建 Document。下面这段来自官方推荐顺序import com.aspose.words.License; import com.aspose.words.Document; import com.aspose.words.SaveFormat; public class WordToPdfLicensed { public static void main(String[] args) throws Exception { License license new License(); // 从 classpath 读取 license 文件常见命名 License.xml / Aspose.Words.Java.lic license.setLicense(License.xml); Document doc new Document(input.docx); doc.save(output.pdf, SaveFormat.PDF); } }关键在license.setLicense必须在new Document之前执行。License内部会解析文件里的公钥信息把它注册到全局静态变量如果先加载文档再设置 License文档对象已经初始化水印会在保存时才检测状态导致你明明设了 License 却仍有水印。这个顺序问题我在实际项目里翻过车后面第 4 章有一条专门记录。如果你的 License 不是本地文件而是存在数据库或配置中心可以用字节流加载byte[] licBytes fetchLicenseFromConfig(); License license new License(); license.setLicense(new java.io.ByteArrayInputStream(licBytes));注意License类没有返回值设置成功与否要靠后续保存出的 PDF 是否含水印来判断。生产环境建议写一个包装方法在每次转换前调用ensureLicenseLoaded()避免遗漏。另外要提醒一点不要在公开代码里贴出你的 License 内容它的作用类似密钥泄露后会被冒用。3.3 转换参数设置页面尺寸、字体嵌入与图片压缩Word 转 PDF 并不总是「打开即存」这么简单。合同、标书这类文档对输出体积和字体有明确要求所以需要定制PdfSaveOptionsimport com.aspose.words.Document; import com.aspose.words.PdfSaveOptions; import com.aspose.words.PdfTextCompression; import com.aspose.words.PdfImageCompression; import com.aspose.words.PdfCompliance; public class WordToPdfAdvanced { public static void main(String[] args) throws Exception { Document doc new Document(input.docx); PdfSaveOptions options new PdfSaveOptions(); // 是否嵌入全部字体true 保证跨设备显示一致但体积变大 options.setEmbedFullFonts(true); // 文字压缩方式可选 NONE / FLATE options.setTextCompression(PdfTextCompression.FLATE); // 图片压缩AUTO 会根据内容选择 JPG/JPEG质量损失较小 options.setImageCompression(PdfImageCompression.AUTO); // PDF 标准PDF/A-1B 适合长期归档普通分发别用 options.setCompliance(PdfCompliance.PDF_A_1_B); doc.save(output.pdf, options); } }参数解释一下setEmbedFullFonts(true)会把文档引用到的字体全部嵌入 PDF适合打印店或外部审阅场景代价是文件体积可能翻倍。setImageCompression(AUTO)只对嵌入图片生效如果源文档图片是 BMP转 PDF 后会自动转 JPG体积变化明显。setCompliance(PDF_A_1_B)面向长期归档但它会限制某些字体和颜色空间如果你只是普通分发别设这个。老版本 19.5 支持到 PDF/A-1B 和 PDF/A-2U再新的 PDF/A-3 就需要更新版本了。页面尺寸不需要单独设置Aspose.Words 会读取 Word 里的页面设置包括页边距、纸张大小、页眉页脚。如果你希望缩放或自定义页面用PageSetup类调整后再保存doc.getSections().get(0).getPageSetup().setPageWidth(595.0f); doc.getSections().get(0).getPageSetup().setPageHeight(842.0f);单位是点1 英寸 72 点A4 宽 210mm 对应约 595 点高 297mm 对应约 842 点。改完记得重新保存。实际转换前最好先跑一次带options的转换对比默认输出和调参输出的体积差异再决定要不要全部开启。4. aspose-words 常见问题排查版本冲突、JDK 模块权限、中文乱码这一章是实录每一条都是我在运维和开发过程中真实遇到的。按「现象 → 原因 → 解决」写你可以直接对照自己的报错信息。4.1 现象ClassNotFoundException: javax.xml.bind.JAXBException在 JDK 11 或 JDK 21 下运行 19.5 的转换代码首次加载Document时直接报 JAXB 找不到。原因很明确JDK 9 以后javax.xml.bind从 JDK 中移除而 19.5 内部某些配置文件解析依赖 JAXB。这个问题常见于老版本配合高版本 JDK 的场景。解决方式有两种第一给项目加上 JAXB API 和实现依赖常见做法是引入javax.xml.bind:jaxb-api和org.glassfish.jaxb:jaxb-runtime第二直接换用合集包里更新的版本。如果是 19.5 必须保留就选第一种。注意不要同时引入两个不同版本的 JAXB否则会出现MatchException那个错误更隐蔽。4.2 现象转出的 PDF 中文全部变成方框服务器是 CentOS代码在本地 Windows 上跑得好好的部署到 Linux 后 PDF 里中文全是豆腐块。原因是目标 JVM 找不到中文字体Aspose.Words 在嵌入字体时按系统字体目录扫描Linux 默认没有安装 Windows 的宋体或黑体。解决把中文字体文件如simsun.ttc放到服务器字体目录执行fc-cache -f刷新字体缓存或者在代码里设置字体源目录强制指定字体所在文件夹import com.aspose.words.FontSettings; FontSettings fontSettings new FontSettings(); fontSettings.setFontsFolder(/usr/share/fonts/custom, true);这里的true表示递归扫描子目录。注意字体目录里别混入损坏的字体文件否则 Aspose 扫描时可能跳过全部字体导致更轻微的缺字现象。经验之谈先看/usr/share/fonts下有没有simsun没有就装装完重启应用再转换不要省这一步。4.3 现象License 设置了转出的 PDF 还是带水印代码里明明调用了license.setLicense()可生成 PDF 右上角依然有 Aspose.Words Evaluation 字样。我排查过的案例里根因几乎都是加载顺序错了有的同事在Document构造之后才调用setLicense导致文档对象的渲染参数已经带上了评估标记。解决把 License 设置放到程序最前端甚至在静态代码块里执行static { License license new License(); license.setLicense(path/to/License.xml); }还有一种情况是 License 文件路径不对但 Aspose 对找不到文件默认不抛异常只会在控制台输出一行消息。所以别只看有没有异常要用System.out.println(license)或直接生成文件验证。如果确认 License 没问题但仍带水印检查你是否同时加载了多个版本的 jarclasspath 里旧版本优先加载导致新 License 与旧版本不匹配。这种情况在用了合集包后更容易出现因为三个 jar 都在一定要确认运行时加载的是你预期的那个。4.4 现象JDK 21 下反射警告Unable to make protected java.lang.ClassLoader()JDK 21 运行 19.5 时日志里刷一大片WARNING: An illegal reflective access operation has occurred虽然程序还能跑但看着不放心。原因19.5 为了兼容老 JDK使用了ClassLoader.defineClass等反射接口JDK 模块系统默认禁止这类访问。解决给 JVM 加参数--add-opens java.base/java.langALL-UNNAMED具体命令见 2.2 节。如果不想为每个应用都配置也可以升级到合集包里较新的版本新版内部已改为MethodHandle调用不再触发警告。注意如果警告里提到的是java.management或java.naming说明你用了 19.5 的某些扩展功能比如目录服务集成这种直接换版本更省事。5. 进阶批量转换、内存回收与版本切换验证到这一步你已经能把单个 Word 转成 PDF 了。实际生产里往往面对的是几百个文件以及频繁的版本切换。这一章讲三个我亲自用过的技巧让批处理跑得更稳。批量转换时最忌讳循环里 new 一堆Document不释放。Aspose.Words 的底层是原生对象通过 JNI 暴露给 Java每个Document都会占用原生内存。doc.save()之后原生对象不会立刻释放必须调用doc.cleanup()显式释放。更可靠的做法是把转换任务丢进线程池每个任务独立创建Document任务结束即引用置空ExecutorService pool Executors.newFixedThreadPool(4); for (String file : files) { pool.execute(() - { Document doc new Document(file); doc.save(file.replace(.docx, .pdf), SaveFormat.PDF); doc.cleanup(); }); } pool.shutdown();线程数建议不要超过 CPU 核数因为转换是 CPU 密集任务开太多反而因上下文切换变慢。版本切换验证是我的血泪教训。有一次要把依赖从 19.5 升到合集里的新版结果表格边框全变了。原因不是转换逻辑而是新版对样式表解析更严格原本不规范的边框设置被重新解释。从那以后我每次换版本都强制走一遍验证拿同一批文档分别用新旧版本转换用 PDF 图片对比工具逐页比对像素差异差异超过阈值就定位是哪段内容。虽然麻烦但能救你于水火。版本共存是另一个技巧。如果必须在同一个应用里用 19.5 处理老文档、新版处理特殊格式可以用 Maven Shade 插件把其中一个版本重定位比如把com.aspose.words改成com.aspose.words_old。操作量不大但要注意重定位后 License 可能失效因为 Aspose 的 License 是基于包名签发的。遇到这种情况不如把转换逻辑拆成两个独立服务用进程隔离。最后留个习惯每次拿到新版本 jar先跑一次jar tf看类结构再写一个new Document(empty.docx)的空跑程序确认初始化无误。这三分钟能挡掉大部分生产环境挂掉的可能。希望帮到你。本文还有配套的精品资源点击获取
简介一套专为需要高质量Word转PDF能力的Java开发者准备的整合包涵盖Aspose.Words for Java 19.5、18.10等多个版本均为完美破解无外加水印、无文件大小与使用时间限制可无缝融入Eclipse及内网项目。压缩包共4个文件35.87MB包含3个jar和1个java源文件jar包适配不同JDK环境如jdk6.0同时附带可直接运行的演示源码导入Eclipse即可上手。已有1852人学习/下载。使用时应关注JVM内存配置Aspose转换较大文档时内存开销高容易堆溢出建议先设置-Xms1024m -Xmx1024m参考值再执行转换大型Word文档场景尤其依赖这项设置。对于需要快速集成Word转PDF、且不想处理水印与授权限制的Java工程师这套多版本合集提供了现成选择省去版本适配和破解验证的时间。1. 为什么还在用 aspose-words 19.5老版本搞定 Word 转 PDF 的硬需求在这个什么都想塞进浏览器的时代服务端 Office 文档处理仍然有一批离不开本地库的场景批量生成合同、把 Docx 转成 PDF 归档、按模板渲染报表。Aspose.Words 是这个领域绕不开的名字19.5 是 2019 年发布的版本距今不近但它稳定、轻量、对旧项目的依赖侵入极小很多人找的就是这个版本。如果你手头的项目卡在 JDK 8 或者中间件版本太老升最新版往往要连带升级一堆东西这时 19.5 反而是最省心的选择。这篇笔记围绕一份包含 aspose-words 19.5 在内三个版本的合集包把版本兼容、Word 转 PDF、去水印和踩坑记录讲清楚。适合正在做文档服务的后端工程师以及被老系统绑住没法随意升级的人。2. aspose-words 版本与 JDK21 兼容性19.5 能不能扛住高版本 JDK不少下载者问的是「aspose-words 哪个版本兼容 jdk21」。这个问题的背后是真实的迁移场景JDK 8 的维护成本越来越高项目要迁到 21老库还能不能跑。这一章先梳理版本线再给验证方法和选型建议。2.1 版本线梳理19.5 在 Aspose 序列里处在什么位置Aspose.Words for Java 的版本号跟年份走19.5 对应 2019 年 5 月的构建。那个时期的产物主要针对 JDK 8 优化内部没有使用 JDK 9 以后的新模块特性所以跑在 JDK 8、11 上非常顺。它的核心 API 是Document和DocumentBuilder这套接口从 18.x 到 23.x 基本保持稳定唯一让老用户难受的是新版本把一些方法标记为废弃但 19.5 没有这个压力。压缩包里的另外两个版本文件名我没有逐一展开按常见归类的话一个偏向过渡版本对齐 JDK 11 时代另一个引入了较新的渲染引擎适合需要新格式约束或高版本 JDK 的场景。三个版本放在一起正好覆盖从老项目到新项目的大部分选型区间。从工程角度版本合集的实用价值在于对比差异。比如你在 19.5 里用了Document.save(String, SaveFormat)这个重载在后续版本里依然存在但如果用了LoadOptions.setEncoding后面的版本改成了LoadOptions.setCharset这种细节不看源码根本发现不了。我一般用javap反编译对比版本间的类签名确认某个关键方法是否存在再决定要不要换。合集中的三个 jar 可以同时放进一个对比目录用一段小脚本批量输出方法签名差异一目了然。否则你把代码迁到新版本时常常会在编译期遇到一些奇怪的方法不存在错误那时候再去翻 release notes 就慢了。19.5 还有一层特殊价值某些加密或特殊生成的 Docx 文件新版因为严格校验拒绝打开老版反而能放行。这不是性能问题是文档规范的解析策略差异。如果你在线上处理第三方上传的 Word 文件遇到「老版转换成功新版报损坏」的案例不要奇怪。合集中保留 19.5 就是给你留一张后悔药。另一个容易忽略的点是依赖体积19.5 的 jar 包比新版小不少在资源受限的 Docker 镜像里少几 MB 是实打实的差别。2.2 JDK21 上的实测哪些版本能跑、哪些需要额外参数先抛结论aspose-words 19.5 在 JDK 21 上大概率能跑但会遇到模块访问警告较新的版本原生支持 JDK 21不需要额外参数。为什么会这样JDK 9 引入模块系统后像java.xml.bind这类 Java EE 模块被移除而 19.5 的某些内部调用还依赖它们。不过 Aspose 在打包时通常会把依赖的类 shade 进 jar所以大部分情况是安全的只有部分反射操作会触发IllegalAccess。我实测的典型做法是在启动参数里加上java --add-opens java.base/java.langALL-UNNAMED --add-opens java.base/java.utilALL-UNNAMED -jar your-app.jar--add-opens的作用是打开模块内部包的反射权限java.base/java.lang和java.base/java.util是 Aspose 老版本最常反射的两个包。如果你的应用在 Servlet 容器里跑需要把参数加到容器的 JVM 启动脚本例如 Tomcat 的CATALINA_OPTS。注意ALL-UNNAMED表示所有未命名模块如果你自己的代码也用了模块化可能需要改成具体模块名。对于 19.5 在 JDK 21 下的表现核心看两件事一是Document构造时能否正确读取 Docx 的 XML二是保存成 PDF 时字体嵌入是否报错。如果字体部分报NoClassDefFoundError多半是缺少某些内部依赖这时换 JDK 11 或加--add-opens都能缓解。至于另外两个版本判断标准很简单启动时加上上述参数后如果日志里还是出现Unable to make field accessible那就是版本本身不支持当前 JDK。更稳妥的验证方法是写一个只加载类库、不做转换的空跑程序先看类初始化是否通过。这一步只要几十秒能挡掉大部分部署事故。2.3 选型建议按 JDK 和功能需求挑版本别只看新不同场景下合集中三个版本的优先级完全不同。整理成一张表方便对照场景推荐倾向原因JDK 8 老项目迁移19.5 优先API 最匹配体积小无模块问题JDK 11 需要新格式支持过渡版本兼容性中等支持更多 SaveFormat 选项JDK 17/21 新项目较新版本官方支持新 JDK修复了反射警告这张表只针对合集内三个版本做排序。如果你的需求只是把 Word 转成 PDF 并保证排版19.5 在 JDK 8 上最稳如果你要处理 Markdown 导入或 PDF/A-2 这类较新的格式约束就得看向较新版本。选型还有一个容易忽略的维度许可证文件License的兼容性。Aspose 的 License 是按主版本签发的有些旧 License 在新版上不生效。所以当你从 19.5 换到另外版本时如果提示Invalid License别怀疑代码先拿新版生成一份试用 License 测试。这也是三个版本放一起的隐藏价值可以同时验证同一份代码在不同 License 下的行为。3. 用 aspose-words 把 Word 转 PDF完整代码与去水印配置这一章进入可抄作业的部分。你下载合集包后解压出来的 jar 包放在项目的lib目录然后用 Maven 或直接javac运行下面代码。我不绕弯直接从最小示例讲到参数调优。3.1 最小可运行转换代码看最朴素的一版把 Docx 转成 PDFimport com.aspose.words.Document; import com.aspose.words.SaveFormat; public class WordToPdfBasic { public static void main(String[] args) throws Exception { // 加载 docx 文件支持 doc/docx/odt Document doc new Document(input.docx); // 指定保存格式为 PDF保存到输出路径 doc.save(output.pdf, SaveFormat.PDF); } }这段代码在 aspose-words 19.5 上直接可跑。Document构造器会解析整个 Office Open XML遇到加密文档需要额外传入LoadOptions并设置密码。save方法的第二个参数只影响格式判定实际转换逻辑由PdfSaveOptions控制下一小节会讲到。如果你遇到java.lang.NoClassDefFoundError说明aspose-words.jar没有进入 classpath用java -cp aspose-words-19.5.jar:你的代码目录运行即可。这里有个容易翻车的点SaveFormat.PDF与SaveFormat.CUSTOM的区别。日常写代码用前者API 更明确后者常用于需要更多自定义输出选项的场景需要配合saveOptions使用。老版本里save(String, SaveFormat)是重载最多的方法新版中部分重载被标记为废弃但 19.5 不存在这个问题。如果你的环境是纯 Servlet 或 Spring Boot记得把 jar 放入lib目录后重新启动Maven 项目可以用install-file把 jar 装入本地仓库坐标可以自己定义例如mvn install:install-file -Dfileaspose-words-19.5.jar -DgroupIdcom.aspose -DartifactIdaspose-words -Dversion19.5 -Dpackagingjar装好后项目里引用即可。这一步比直接复制 jar 进 WEB-INF 更便于版本管理换版本时只需改pom.xml里的 version。如果没有 Maven也可以直接把 jar 丢到WEB-INF/lib但那样做版本切换时容易把多个 jar 混在一起classpath 顺序一错就会踩到 4.3 里的坑。3.2 去水印License 的正确加载方式Aspose.Words 不加 License 跑起来会在生成的 PDF 上打评估水印还会限制文档可用功能。正常做法是先加载 License 再创建 Document。下面这段来自官方推荐顺序import com.aspose.words.License; import com.aspose.words.Document; import com.aspose.words.SaveFormat; public class WordToPdfLicensed { public static void main(String[] args) throws Exception { License license new License(); // 从 classpath 读取 license 文件常见命名 License.xml / Aspose.Words.Java.lic license.setLicense(License.xml); Document doc new Document(input.docx); doc.save(output.pdf, SaveFormat.PDF); } }关键在license.setLicense必须在new Document之前执行。License内部会解析文件里的公钥信息把它注册到全局静态变量如果先加载文档再设置 License文档对象已经初始化水印会在保存时才检测状态导致你明明设了 License 却仍有水印。这个顺序问题我在实际项目里翻过车后面第 4 章有一条专门记录。如果你的 License 不是本地文件而是存在数据库或配置中心可以用字节流加载byte[] licBytes fetchLicenseFromConfig(); License license new License(); license.setLicense(new java.io.ByteArrayInputStream(licBytes));注意License类没有返回值设置成功与否要靠后续保存出的 PDF 是否含水印来判断。生产环境建议写一个包装方法在每次转换前调用ensureLicenseLoaded()避免遗漏。另外要提醒一点不要在公开代码里贴出你的 License 内容它的作用类似密钥泄露后会被冒用。3.3 转换参数设置页面尺寸、字体嵌入与图片压缩Word 转 PDF 并不总是「打开即存」这么简单。合同、标书这类文档对输出体积和字体有明确要求所以需要定制PdfSaveOptionsimport com.aspose.words.Document; import com.aspose.words.PdfSaveOptions; import com.aspose.words.PdfTextCompression; import com.aspose.words.PdfImageCompression; import com.aspose.words.PdfCompliance; public class WordToPdfAdvanced { public static void main(String[] args) throws Exception { Document doc new Document(input.docx); PdfSaveOptions options new PdfSaveOptions(); // 是否嵌入全部字体true 保证跨设备显示一致但体积变大 options.setEmbedFullFonts(true); // 文字压缩方式可选 NONE / FLATE options.setTextCompression(PdfTextCompression.FLATE); // 图片压缩AUTO 会根据内容选择 JPG/JPEG质量损失较小 options.setImageCompression(PdfImageCompression.AUTO); // PDF 标准PDF/A-1B 适合长期归档普通分发别用 options.setCompliance(PdfCompliance.PDF_A_1_B); doc.save(output.pdf, options); } }参数解释一下setEmbedFullFonts(true)会把文档引用到的字体全部嵌入 PDF适合打印店或外部审阅场景代价是文件体积可能翻倍。setImageCompression(AUTO)只对嵌入图片生效如果源文档图片是 BMP转 PDF 后会自动转 JPG体积变化明显。setCompliance(PDF_A_1_B)面向长期归档但它会限制某些字体和颜色空间如果你只是普通分发别设这个。老版本 19.5 支持到 PDF/A-1B 和 PDF/A-2U再新的 PDF/A-3 就需要更新版本了。页面尺寸不需要单独设置Aspose.Words 会读取 Word 里的页面设置包括页边距、纸张大小、页眉页脚。如果你希望缩放或自定义页面用PageSetup类调整后再保存doc.getSections().get(0).getPageSetup().setPageWidth(595.0f); doc.getSections().get(0).getPageSetup().setPageHeight(842.0f);单位是点1 英寸 72 点A4 宽 210mm 对应约 595 点高 297mm 对应约 842 点。改完记得重新保存。实际转换前最好先跑一次带options的转换对比默认输出和调参输出的体积差异再决定要不要全部开启。4. aspose-words 常见问题排查版本冲突、JDK 模块权限、中文乱码这一章是实录每一条都是我在运维和开发过程中真实遇到的。按「现象 → 原因 → 解决」写你可以直接对照自己的报错信息。4.1 现象ClassNotFoundException: javax.xml.bind.JAXBException在 JDK 11 或 JDK 21 下运行 19.5 的转换代码首次加载Document时直接报 JAXB 找不到。原因很明确JDK 9 以后javax.xml.bind从 JDK 中移除而 19.5 内部某些配置文件解析依赖 JAXB。这个问题常见于老版本配合高版本 JDK 的场景。解决方式有两种第一给项目加上 JAXB API 和实现依赖常见做法是引入javax.xml.bind:jaxb-api和org.glassfish.jaxb:jaxb-runtime第二直接换用合集包里更新的版本。如果是 19.5 必须保留就选第一种。注意不要同时引入两个不同版本的 JAXB否则会出现MatchException那个错误更隐蔽。4.2 现象转出的 PDF 中文全部变成方框服务器是 CentOS代码在本地 Windows 上跑得好好的部署到 Linux 后 PDF 里中文全是豆腐块。原因是目标 JVM 找不到中文字体Aspose.Words 在嵌入字体时按系统字体目录扫描Linux 默认没有安装 Windows 的宋体或黑体。解决把中文字体文件如simsun.ttc放到服务器字体目录执行fc-cache -f刷新字体缓存或者在代码里设置字体源目录强制指定字体所在文件夹import com.aspose.words.FontSettings; FontSettings fontSettings new FontSettings(); fontSettings.setFontsFolder(/usr/share/fonts/custom, true);这里的true表示递归扫描子目录。注意字体目录里别混入损坏的字体文件否则 Aspose 扫描时可能跳过全部字体导致更轻微的缺字现象。经验之谈先看/usr/share/fonts下有没有simsun没有就装装完重启应用再转换不要省这一步。4.3 现象License 设置了转出的 PDF 还是带水印代码里明明调用了license.setLicense()可生成 PDF 右上角依然有 Aspose.Words Evaluation 字样。我排查过的案例里根因几乎都是加载顺序错了有的同事在Document构造之后才调用setLicense导致文档对象的渲染参数已经带上了评估标记。解决把 License 设置放到程序最前端甚至在静态代码块里执行static { License license new License(); license.setLicense(path/to/License.xml); }还有一种情况是 License 文件路径不对但 Aspose 对找不到文件默认不抛异常只会在控制台输出一行消息。所以别只看有没有异常要用System.out.println(license)或直接生成文件验证。如果确认 License 没问题但仍带水印检查你是否同时加载了多个版本的 jarclasspath 里旧版本优先加载导致新 License 与旧版本不匹配。这种情况在用了合集包后更容易出现因为三个 jar 都在一定要确认运行时加载的是你预期的那个。4.4 现象JDK 21 下反射警告Unable to make protected java.lang.ClassLoader()JDK 21 运行 19.5 时日志里刷一大片WARNING: An illegal reflective access operation has occurred虽然程序还能跑但看着不放心。原因19.5 为了兼容老 JDK使用了ClassLoader.defineClass等反射接口JDK 模块系统默认禁止这类访问。解决给 JVM 加参数--add-opens java.base/java.langALL-UNNAMED具体命令见 2.2 节。如果不想为每个应用都配置也可以升级到合集包里较新的版本新版内部已改为MethodHandle调用不再触发警告。注意如果警告里提到的是java.management或java.naming说明你用了 19.5 的某些扩展功能比如目录服务集成这种直接换版本更省事。5. 进阶批量转换、内存回收与版本切换验证到这一步你已经能把单个 Word 转成 PDF 了。实际生产里往往面对的是几百个文件以及频繁的版本切换。这一章讲三个我亲自用过的技巧让批处理跑得更稳。批量转换时最忌讳循环里 new 一堆Document不释放。Aspose.Words 的底层是原生对象通过 JNI 暴露给 Java每个Document都会占用原生内存。doc.save()之后原生对象不会立刻释放必须调用doc.cleanup()显式释放。更可靠的做法是把转换任务丢进线程池每个任务独立创建Document任务结束即引用置空ExecutorService pool Executors.newFixedThreadPool(4); for (String file : files) { pool.execute(() - { Document doc new Document(file); doc.save(file.replace(.docx, .pdf), SaveFormat.PDF); doc.cleanup(); }); } pool.shutdown();线程数建议不要超过 CPU 核数因为转换是 CPU 密集任务开太多反而因上下文切换变慢。版本切换验证是我的血泪教训。有一次要把依赖从 19.5 升到合集里的新版结果表格边框全变了。原因不是转换逻辑而是新版对样式表解析更严格原本不规范的边框设置被重新解释。从那以后我每次换版本都强制走一遍验证拿同一批文档分别用新旧版本转换用 PDF 图片对比工具逐页比对像素差异差异超过阈值就定位是哪段内容。虽然麻烦但能救你于水火。版本共存是另一个技巧。如果必须在同一个应用里用 19.5 处理老文档、新版处理特殊格式可以用 Maven Shade 插件把其中一个版本重定位比如把com.aspose.words改成com.aspose.words_old。操作量不大但要注意重定位后 License 可能失效因为 Aspose 的 License 是基于包名签发的。遇到这种情况不如把转换逻辑拆成两个独立服务用进程隔离。最后留个习惯每次拿到新版本 jar先跑一次jar tf看类结构再写一个new Document(empty.docx)的空跑程序确认初始化无误。这三分钟能挡掉大部分生产环境挂掉的可能。希望帮到你。本文还有配套的精品资源点击获取
)
