简介：Jacob（Java COM Bridge）是用于在Java程序中调用Windows COM组件及ActiveX对象的关键桥梁，特别适合需要与Word、Excel等Office应用或系统COM接口交互的Java开发者。资源包汇集jacob 1.15、1.16、1.17和1.9四个版本：1.15至1.17在API易用性、COM组件兼容性与稳定性上逐步演进，1.9则适合运行环境受限的旧工程，多版本同包便于新项目按需选型、旧项目平稳升级。压缩包共159个文件，除4个jar库与5个动态库外，还包含javadoc格式的html接口文档、properties配置示例、txt使用说明、css样式及gif示意等辅助文件，dll已按x86/x64区分，覆盖从API查阅、环境配置到实际调用的完整链路。整套资源约705KB，轻量易传，随包即可获得不同版本对比与配置要点。目前已有550人浏览学习，多版本合并打包省去了逐一下载与版本匹配的麻烦，适合需要快速集成Jacob、排查COM调用异常或维护历史项目的Java工程师，也可作为版本升级前的API差异参考。
1. 四个 jacob 版本号同时出现，不是选择困难，是环境分裂
做过 Java 调用 Windows 本地组件的人，大概率都见过 jacob 这个名字。它是一个 Java-COM 桥接库，让 JVM 里的代码能直接操作 Word、Excel、WMI 这些 COM 组件，不用再包一层 C++ 或者命令行。标题里同时抛出 1.9、1.15、1.16、1.17 四个版本和 jar 包、动态库两类产物，说明你十有八九遇到了一个老系统改造或者多环境兼容的场景：有的机器是 32 位 JDK，有的机器是 64 位 JDK，有的机器还在跑 JDK 8，有的已经切到 JDK 11。这篇文章就围绕这四个版本把 jar 包和动态库的分工、选型、配置、调通路径和踩坑记录讲透，目标是你拿回去就能照着把环境搭起来、把第一个 COM 调用跑通，然后知道什么时候该升级、什么时候别乱动。
2. 先弄清 1.9、1.15、1.16、1.17 到底差在哪：版本差异与选型依据
2.1 从调用链看懂 jar 包和动态库的分工
jacob 之所以叫“桥”，是因为它把两条完全不同的技术栈接在一起。Java 这边走的是 JNI 声明，Windows 那边走的是 COM 接口调用，中间隔着一层本地动态库。jar 包里装的是一组 Java 类，主要是com.jacob.activeX、com.jacob.com两个包，负责封装 COM 的IDispatch调用、变体类型Variant、COM 线程模型这些概念。动态库则是真正的 JNI 实现，负责把 Java 的 native 方法翻译成 COM API 调用，再处理参数类型转换、返回值包装和异常传递。
所以“jar 包和动态库”不是二选一的关系，是配对关系。只放 jar 包不放动态库，运行时报UnsatisfiedLinkError；只放动态库不放 jar 包，编译直接失败。版本号的匹配也遵循这个逻辑：jar 包里的 native 方法声明和动态库的导出符号必须对得上，跨版本混用很容易出现方法找不到或者参数解析错乱。
我一般会把 jar 包和动态库看成“同一个版本的左右手”，升级就一起升，降级就一起降。项目里常出现一种尴尬情况：依赖声明里写的是 1.17，但是系统PATH里躺着一个旧项目留下的 1.9 dll，运行时不报错则已，一报错就是玄学级的问题，后面专门有一章讲这个。
2.2 四个版本的关键边界：位数、JDK、产物形态
先说 1.9。这个版本非常老，它的动态库只有 32 位构建，而且对 JDK 版本的容忍度有限。在 JDK 8 的 32 位环境下跑老代码，用它通常没问题，因为当年大量项目就是在那个组合下运行的。但如果你现在用的是 64 位 JDK，1.9 的动态库直接加载失败，java.library.path配得再对也没用，JVM 会明确告诉你无法加载这个库。
1.15 是一个分水岭。从这一版开始，jacob 的构建产物里同时出现 x86 和 x64 两个动态库，jar 包本身是跨平台的，但动态库要按照 JVM 位数选择对应文件。也就是说，用 64 位 JDK 必须配 64 位 dll，用 32 位 JDK 必须配 32 位 dll，混搭是跑不起来的。
1.16 和 1.17 在 API 层面基本保持稳定，主要变化集中在几处：一是对较新 JDK 的兼容性调整，尤其是 JDK 9 以后的模块系统对 native 库加载路径的约束；二是在 COM 调用的边界处理上更严谨，比如Variant的类型转换、Dispatch调用的错误码映射；三是动态库的发布形态更规范，位数标识直接在文件名里体现，一眼能看出该选哪个。
这里需要特别提醒：1.16 和 1.17 之间不存在“必须升”的理由，如果你的业务代码已经从 1.15 跑通，且 JDK 版本没变，停在 1.16 完全没问题。1.17 更多是给新项目或者准备迁移到新 JDK 的项目用的。版本之间没有换汤不换药，只是没必要为了追新而追新。
2.3 选型建议：什么情况该锁哪个版本
选型不是看哪个版本号最新，而是看三个约束条件：JVM 位数、JDK 主版本、目标机器的部署方式。按我接触过的实际场景，可以这样快速判断。
JDK 8 且 32 位、老项目动不了，锁 1.9。这个组合虽然老，但稳定，前提是别去碰新 JDK 特性，也别在 64 位 JVM 上硬跑。JDK 8 且 64 位，建议锁 1.15 或 1.16，这是我见过最常见的组合，大量企业内部系统至今跑在这个配置上。JDK 11 或更高，直接上 1.17，因为新 JDK 对 native 库的加载路径和模块访问权限更严格，老版本确实容易翻车。
还有一个容易被忽略的点：如果是纯新项目，且不确定目标机器的 JDK 位数，我建议直接按 64 位设计，因为现在新部署的 JDK 几乎都是 64 位，32 位环境只会越来越少。反过来，如果是给存量机器做兼容，一定要先问清楚那台机器上的 JVM 到底是哪个位数，这个信息比版本号本身还重要。
3. 把 jacob 的 jar 包和动态库装进本地工程：目录结构、加载方式与校验
3.1 本地仓库与依赖声明
jacob 的 jar 包并不是所有公共仓库都有稳定收录，尤其是 1.9 这种老版本，很多时候要从旧项目的lib目录里捞。所以工程里的第一件事，是把对应版本的 jar 包装进本地仓库或者直接在工程里建一个libs目录管理。
用 Maven 的话，我倾向于直接把 jar 装进本地仓库，这样pom.xml里就能正常声明依赖，团队其他人拉下来也能构建。命令如下：
mvn install:install-file \ -Dfile=libs/jacob.jar \ -DgroupId=com.jacob \ -DartifactId=jacob \ -Dversion=1.17 \ -Dpackaging=jar这条命令把libs/jacob.jar装进本地 Maven 仓库，同时指定了坐标。之后在pom.xml里这样声明：
<dependency> <groupId>com.jacob</groupId> <artifactId>jacob</artifactId> <version>1.17</version> </dependency>参数说明：Dfile指向 jar 包的物理路径，DgroupId和DartifactId是坐标，Dversion是版本号，这组坐标要保证和实际 jar 版本严格对应。装进本地仓库的好处是后续构建不需要再人工拷贝 jar 包，缺点是如果团队用了私服，还需要额外执行一次 deploy。
还有一种更直接的做法：把 jar 包放在工程根目录的libs下，然后让 Maven 以系统依赖的方式引入。写法是：
<dependency> <groupId>com.jacob</groupId> <artifactId>jacob</artifactId> <version>1.17</version> <scope>system</scope> <systemPath>${project.basedir}/libs/jacob.jar</systemPath> </dependency>这种做法适合快速跑通，但system作用域在打包时会带来一些麻烦，尤其是用 Spring Boot 的spring-boot-maven-plugin打包时，系统依赖很容易漏进最终的 jar 里。所以我的习惯是：临时调试用systemPath，正式工程一律先装本地仓库再正常声明。
3.2 动态库放哪儿：三种常见做法与 java.library.path 说明
jar 包解决的是 Java 类的问题，动态库解决的是本地方法实现的问题。JVM 加载动态库时，会按照java.library.path指定的路径去搜索，这个路径的默认值通常包括了 JVM 所在目录、当前工作目录和系统PATH。配置动态库的常见做法有三种。
第一种，把动态库放到 JDK 的bin目录或 JRE 的bin目录下。这是最省事的方案，适合个人开发机，因为 JVM 启动时默认就会搜索这个目录。但生产环境这么干不太合适，因为 JDK 目录本来就属于系统级位置，动它需要管理员权限，而且多版本 JDK 切换时容易覆盖错。
第二种，通过启动参数显式指定路径，这是我最推荐的方式。命令长这样：
java -Djava.library.path=./libs -jar myapp.jar./libs目录下放对应版本的动态库文件。这个方式的好处是部署时只需要带上一个libs目录，升级版本时换文件就行，不用碰 JVM 安装目录。需要注意，-Djava.library.path会覆盖 JVM 的默认搜索路径，而不是追加。如果原来的默认路径里还有其他依赖库，最好把默认路径也拼进来，比如：
java -Djava.library.path=./libs:${JAVA_HOME}/bin -jar myapp.jar第三种，在 Java 代码里通过System.load显式加载绝对路径。适合动态库位置不确定、需要在运行时根据配置读取的场景。代码是这样的：
System.load("D:/deploy/libs/jacob-1.17-x64.dll");逻辑说明：System.load的参数必须是完整路径，包含文件名和后缀。这个方式最灵活，但要注意路径分隔符在 Windows 下同样支持正斜杠，写D:/deploy/libs比D:\\deploy\\libs更不容易踩转义坑。
3.3 加载成功后如何验证
配置完环境，第一件事不是写业务代码，而是验证 jar 包和动态库是否成功配对。写一个最简启动类：
import com.jacob.com.LibraryLoader; public class JacobEnvCheck { public static void main(String[] args) { LibraryLoader.loadJacobLibrary(); System.out.println("jacob native library loaded"); System.out.println("java.library.path=" + System.getProperty("java.library.path")); } }逻辑说明：LibraryLoader.loadJacobLibrary()是 jacob 内部根据当前 JVM 位数自动加载对应动态库的入口。如果这一步抛UnsatisfiedLinkError，说明动态库没找到或者位数不对；如果能正常打印出路径信息，说明环境层已经通了。
正常情况下，运行后能看到类似这样的输出：
jacob native library loaded java.library.path=./libs这一步验证通过之后，再往下写 COM 调用才有意义。很多项目一上来就写业务代码，结果报错时分不清到底是环境问题还是 API 使用问题，排查成本翻倍。
4. 最小可用路径：用 jacob 调通一个 COM 组件（以 Word 为例）
4.1 初始化 COM 线程与调用入口
jacob 对 COM 的线程模型有要求。COM 的初始化分为 STA（单线程单元）和 MTA（多线程单元），Word、Excel 这类 Office 组件通常是 STA 模型，要求创建和调用它的线程必须完成 COM 初始化。
在 jacob 里，ComThread.init()负责在当前线程初始化 COM，ComThread.Release()负责释放。这个配对关系类似数据库连接的打开和关闭，不能只开不关，也不能重复开启。常见做法是在入口处初始化，在 finally 块里释放。
import com.jacob.com.ComThread; import com.jacob.activeX.ActiveXComponent; import com.jacob.com.Dispatch; public class WordDemo { public static void main(String[] args) { ComThread.init(); try { ActiveXComponent word = new ActiveXComponent("Word.Application"); Dispatch.put(word, "Visible", false); Dispatch.call(word, "Quit"); } finally { ComThread.Release(); } } }逻辑说明：ComThread.init()初始化当前线程的 COM 环境；new ActiveXComponent("Word.Application")通过 COM ProgID 创建 Word 应用实例；Dispatch.put设置属性；Dispatch.call调用方法。这里Visible设成false是为了让 Word 在后台运行，不弹出界面。
注意ComThread.Release()的大小写，jacob 的 API 里方法名是Release，小写r会直接编译报错。这个细节在早期版本尤其折磨人。
4.2 最小调用代码与返回值说明
建立一个 Word 文档并写入一段文字，是最经典的最小调用场景。代码不复杂，但每一步都有值得拆解的地方。
import com.jacob.com.ComThread; import com.jacob.activeX.ActiveXComponent; import com.jacob.com.Dispatch; public class WordWriteDemo { public static void main(String[] args) { ComThread.init(); try { ActiveXComponent word = new ActiveXComponent("Word.Application"); Dispatch.put(word, "Visible", false); Dispatch documents = Dispatch.get(word, "Documents").toDispatch(); Dispatch doc = Dispatch.call(documents, "Add").toDispatch(); Dispatch selection = Dispatch.get(word, "Selection").toDispatch(); Dispatch.put(selection, "Text", "hello jacob version 1.17"); Dispatch.call(doc, "SaveAs", "D:/tmp/jacob-test.docx"); Dispatch.call(doc, "Close", false); Dispatch.call(word, "Quit"); } finally { ComThread.Release(); } } }逐行说明：Dispatch.get(word, "Documents")拿到 Word 的 Documents 集合；Dispatch.call(documents, "Add")新建一个文档；Dispatch.get(word, "Selection")获取当前选区，Word 的选区对象可以直接写入文本；Dispatch.put(selection, "Text", "...")把文本写入选区；SaveAs的第一个参数是完整保存路径；Close的第一个参数false表示不询问是否保存，因为前面已经保存过了。
这里有一个关键点：Dispatch.get和Dispatch.call返回的是Variant类型，包装着 COM 对象或值。如果返回值是一个对象，需要调用.toDispatch()转成Dispatch才能继续往下传。漏掉这个转换是新手最常见的报错来源。
4.3 常见调用写法与释放时机
随着项目变大，你会发现 jacob 有一个很别扭的设计：Dispatch对象没有显式的 close 方法，它依赖 GC 和 COM 线程释放。所以我在项目里通常会封装一层工具类，把所有Dispatch的创建、调用、释放集中在同一个事务范围内。
封装思路大致是这样：
public class WordHelper { private ActiveXComponent word; public void open() { ComThread.init(); word = new ActiveXComponent("Word.Application"); Dispatch.put(word, "Visible", false); } public void close() { if (word != null) { Dispatch.call(word, "Quit"); word = null; } ComThread.Release(); } }逻辑说明：open和close成对出现，业务代码只关心中间的逻辑。这样做的本质是把 COM 线程的生命周期控制在明确的边界内，避免因为异常路径导致ComThread.init()被调用两次或者Quit没有被执行。
释放时机上，我的经验是：进程内同一时刻只允许一个线程持有 COM 初始化状态，多线程场景必须各自init各自Release，不能共享。这个约束是 COM 模型本身决定的，不是 jacob 能绕开的。
5. ClassNotFoundException、UnsatisfiedLinkError 与 DLL 加载失败的排查与避坑
5.1 现象：运行时报UnsatisfiedLinkError: Native Library ... already loaded in another classloader
这个问题在 Web 应用里出现得最多。一个基于 Tomcat 的旧系统部署了多个应用，每个应用都带了 jacob 的 jar 包和动态库，结果启动到第二个应用时直接抛这个错。
原因：动态库是 native 级别的资源，同一个 JVM 进程内，同一个动态库只能被加载一次。Tomcat 为了隔离应用用了不同的 classloader，每个 classloader 都尝试加载同一个 dll，JVM 判定重复加载就直接拒绝。
解决：不要让每个应用自己加载，把 jacob 的 jar 包和 dll 放到 Tomcat 的公共lib目录下，所有应用共享同一份；或者把加载动作收敛到一个公共模块里，由它负责System.load，其他应用只引用这个模块。
5.2 现象：64 位 JVM 配 32 位动态库，报UnsatisfiedLinkError或者Can't load IA 32-bit .dll on a AMD 64-bit platform
这个报错信息其实已经说得很直白了，就是位数不匹配。常见的场景是开发机是 64 位 JDK，但项目里某个老同事从旧机器上拷了一份 32 位的 dll 放进libs目录，大家都没发现。
原因：JNI 动态库和 JVM 位数必须完全一致，32 位 dll 只能配 32 位 JVM，64 位 dll 只能配 64 位 JVM，这一点没有任何回旋余地。
解决：先确认 JVM 位数，再看 dll 位数。确认命令是：
java -version输出里64-Bit字样表示这是 64 位 JVM。然后检查libs目录下的 dll 文件名，按标题里的 1.15、1.16、1.17 版本，位数在文件名里是有区分的。文件名带x64的是 64 位，带x86的是 32 位。文件名没写位数的老版本，只能判断后缀或用工具查看 PE 头，但相比之下，直接从版本对应的构建包里取对应文件是更可靠的选择。
5.3 现象：java.lang.UnsupportedClassVersionError: com/jacob/... has been compiled by a more recent version of the Java Runtime
这个错误出现在用 1.17 版本编译的应用，跑在 JDK 8 环境里。因为新版 jacob 的 jar 包可能用了更高版本的 class 文件格式，老 JVM 读不懂。
原因：jar 包的编译目标版本和运行环境的 JDK 版本不兼容。1.9 的 jar 包通常兼容 JDK 8 及以下，1.15、1.16、1.17 的构建对 JDK 版本要求逐步提升。
解决：如果你的部署环境锁死 JDK 8，优先用 1.15 或 1.16；如果必须用 1.17，那就要把应用服务器的 JDK 升级。升级 JDK 的代价比换 jacob 版本大得多，所以顺序应该是先确认环境，再定版本。
5.4 现象：ClassNotFoundException: com.jacob.com.ComThread
代码编译通过，但运行时报找不到类，而你的pom.xml里明明声明了依赖。
原因：打包环节出了问题。如果你的应用是用 Spring Boot 的可执行 jar 方式发布，而 jacob 是用systemPath引入的，那么这个依赖可能根本没有被打进最终的 fat jar 里。
解决：改用本地仓库方式声明依赖，或者把 jacob 的 jar 包手动解压到BOOT-INF/lib目录下再重新打包。检查手段很简单，用压缩工具打开最终的 jar，搜索com/jacob目录是否存在就能确认。
5.5 现象：能加载 dll，但调用某个 COM 方法时抛COMException: 找不到指定的模块
这种报错最隐蔽，因为环境检查那一步能过，说明 dll 已经加载成功了，问题出在 COM 组件本身的注册状态上。
原因：目标机器上安装的 Office 或者组件缺失，或者 COM 组件没有正确注册。dll 加载成功只说明 jacob 和 JVM 配对成功，并不代表你要调用的 COM 组件存在且可用。
解决：分两段排查。先确认组件存在，用注册表或者命令行工具查看 ProgID。然后确认组件可用，直接用一个小 Java 类单独创建这个组件实例，如果创建失败，问题基本不在 jacob，而在组件安装环境。这个方法比看堆栈更快定位责任方。
6. 版本迁移顺序与快速验证技巧：把老项目从 1.9 搬到 1.17 的实操步骤
如果手里有一个跑了多年的 1.9 老项目，想迁到 1.17，我建议按三条线并行推进，而不是一次性切换。
第一，先把代码层的 API 检查一遍。1.9 到 1.17 之间，com.jacob.com.ComThread、ActiveXComponent、Dispatch这些核心类的用法基本没变，但个别方法的返回值类型和异常处理有调整。做法是把项目里所有import com.jacob.*的文件列出来，逐个编译，让编译器帮你找出不兼容的地方，比人工走查快得多。
第二，把 jar 包和 dll 一起替换，不要逐步升级。也就是说，不推荐先在 1.9 代码上换 1.15 的 jar，再换 1.17 的 dll。直接整套换成 1.17 的 jar 和对应位数的 dll，然后跑一次全量回归。这样出了问题只需要在两个版本之间对比，不需要猜是哪个组合的问题。
第三，写一个快速验证脚本，每次切换版本后先跑它，不用打开什么重型应用。脚本可以做这样一件事：针对目标 COM 组件探活，例如检查 Excel.Application 是否能被创建。核心代码简化后长这样：
public static boolean checkComAvailable(String progId) { ComThread.init(); try { ActiveXComponent comp = new ActiveXComponent(progId); Dispatch.call(comp, "Quit"); return true; } catch (Exception e) { return false; } finally { ComThread.Release(); } }逻辑说明：方法入参是 COM 的 ProgID，例如Word.Application或者Excel.Application。能创建并成功调用Quit，说明这个组件在当前环境下可用；抛异常则说明不可用，具体原因再看异常类型。
这个函数可以作为环境自检的一个入口，在应用启动时记录到日志里，不是每台机器都能创建 Excel 组件，提前探活比业务运行到一半再报错要省心得多。
我个人的习惯是：每个涉及 jacob 的项目，libs目录下只保留当前正在使用的版本，历史的 dll 宁可删掉不要留下。因为那些旧文件会在某个深夜让人误以为是当前版本导致的诡异问题，实际上是从前遗留的幽灵文件。版本切换时，先删旧再放新，然后把java.library.path的配置和实际的 dll 目录对照一眼，多数环境问题就能在启动前被掐灭。希望这组选型和验证思路能帮你在 jacob 的版本迷宫里少绕几个弯。
本文还有配套的精品资源，点击获取
