简介面向Java开发者的jacob 1.20完整资源包解决在Java应用中通过COM桥接调用MS Office组件将Word、Excel、PPT等文档批量转换为PDF的常见需求适合办公自动化、文档处理与桌面端工具开发场景。资源共88个文件压缩包约495KB解压后包含jacob.jar、32位与64位两个dll以及全套开发文档其中大量html为API参考文档md文件涵盖JacobComLifetime生命周期、事件回调、线程模型、从源码构建、Release Notes等说明配合dll与jar可帮助读者快速配置环境并排查调用异常文档中的生命周期与线程模型说明对避免COM调用崩溃尤其有用。已有2010人学习下载。这套资源最大的价值在于平台覆盖完整、文档齐备读者既能直接获取所需DLL与JAR包完成集成也能按需查阅API与专题文档理解实现细节从而更稳妥地实现Office转PDF功能适合需要在不同位数环境下完成文档转换的Java项目开发者。1. jacob 1.20 的 x64/x86 DLL解决什么问题以及它为什么直接决定 JVM 能不能加载某个生产环境的报表任务在凌晨失败日志里没有业务异常只有一行UnsatisfiedLinkError指向jacob-1.20-x64.dll。如果你正在搜这个文件名说明你大概率遇到了同样的事Java 代码要调用 Windows 平台上的 COM 组件可能是导出表格、读取设备数据或者对接某个只能在 Windows 上跑的 ActiveX 控件。JACOB 1.20 就是承担这个任务的 JNI 桥jacob-1.20-x64.dll与jacob-1.20-x86.dll是桥两头真正干活的本地库。这篇文章要解决四件事这两个 DLL 怎么选、怎么放、怎么确认加载成功以及这个老版本最常见的几个坑。2. jacob 1.20 的 x64/x86 怎么选对齐的不是操作系统是 JVM 位数JACOB 1.20 发布的两个 DLL文件名里已经把答案写了一半x64给 64 位 JVMx86给 32 位 JVM。真正让新手反复翻车的是把“操作系统位数”和“JVM 位数”混为一谈。Windows 是 64 位不代表你装的 JDK 就是 64 位反过来Windows 是 32 位也几乎不可能跑 64 位 JDK。判断依据只有一条当前 Java 进程是几位就加载对应的 DLL。2.1 为什么 DLL 位数必须和 JVM 一致加载器的硬规则JACOB 的 DLL 本质是一个 JNI 本地库Java 侧通过System.loadLibrary或System.load把它加载进 JVM 进程。Windows 的加载器在加载 DLL 时会严格校验 DLL 的 PE 架构和当前进程架构是否一致64 位进程加载 32 位 DLL加载器直接拒绝报错内容通常类似 “Cant load IA 32-bit .dll on a 64-bit platform”反过来32 位进程加载 64 位 DLL也会报同样的架构不匹配错误。这里有个容易忽略的点JACOB 的 jar 包在首次实例化 COM 对象时会主动读取sun.arch.data.model这个 JVM 属性然后拼出对应的库名去java.library.path里找文件。也就是说如果你用 64 位 JDK它找的就是jacob-1.20-x64.dll用 32 位 JDK它找的就是jacob-1.20-x86.dll。所以文件名必须原样保留不要手动改成别的名字否则 JACOB 自己找不到文件。2.2 DLL 放哪里项目内 libs 目录优于 System32先搞清楚三个容易混淆的搜索路径它们各自管的事情完全不同路径作用JACOB 相关java.library.pathJVM 加载 JNI 库时搜索的路径JACOB 的 DLL 主要靠它系统PATHWindows 加载器搜索依赖 DLL 的路径DLL 依赖的 VC 运行库可能走这里classpathJava 类文件搜索路径只负责 jar 包和 DLL 无关常见做法是在项目目录下建一个libs/或native/子目录把两个 DLL 都放进去然后在启动参数里用-Djava.library.path指向这个目录。我一般会刻意避开System32这类系统目录一是 64 位系统下System32实际是 64 位目录32 位 DLL 会被重定向到SysWOW64行为很隐蔽二是往系统目录里塞第三方 DLL 会污染全局环境排查问题时很容易怀疑到别的程序头上。把 DLL 收在项目目录里机器上换项目、换版本都干净。2.3 先确认 JVM 位数一行命令加一行代码选 DLL 之前先确认当前 JVM 到底是几位。命令行里执行java -version 21 | findstr /i 64-Bit有输出说明命令行默认的 JVM 是 64 位没输出多半是 32 位。但这里有个坑如果用的是 IDE 或应用服务器它们可能内置了另一套 JRE。更可靠的做法是在 Java 代码里直接打印属性public class JvmArch { public static void main(String[] args) { // sun.arch.data.model 是 HotSpot JVM 提供的属性只返回 32 或 64 System.out.println(JVM data model: System.getProperty(sun.arch.data.model)); // os.arch 在 64 位 Windows 上通常是 amd64在 32 位上是 x86 System.out.println(OS arch: System.getProperty(os.arch)); } }运行一次看sun.arch.data.model的输出。这个值是 JVM 自己报的比看安装目录、看环境变量都可靠。确认完位数后64 位就保留jacob-1.20-x64.dll32 位就保留jacob-1.20-x86.dll另一个文件可以留在目录里备用但不要指望它“顺便”被加载。3. 让 jacob-1.20-x64.dll 被 Java 找到library path 的三种配置与最小冒烟测试选对了 DLL 只是第一步接下来要让 JVM 能在启动时找到它。JACOB 的 jar 本身不负责搬运 DLL它只负责在运行时去java.library.path里按库名搜索。所以配置的核心就一句话把 DLL 所在目录告诉 JVM。下面三种方式我按使用频率从高到低讲。3.1 常规做法用 -Djava.library.path 指向 DLL 目录命令行启动时直接加启动参数java -Djava.library.pathD:\app\jacob-lib -cp app.jar com.example.JacobRunner这里D:\app\jacob-lib是放jacob-1.20-x64.dll的目录。需要注意一旦显式设置了java.library.pathWindows 上默认从系统PATH搜索本地库的规则会被覆盖。如果你的 DLL 还有附带依赖比如某些 VC 运行库需要把依赖目录也写进来用分号分隔。但路径里有分号或空格时引号和分隔符会变得很难缠。我一般会把 DLL 和它可能依赖的本地文件都收进同一个干净的目录然后在启动参数里只指向这一个目录尽量不依赖系统PATH。这样做的另一个好处是目标机器上的环境差异被压缩到最小换机器时只要带上这个目录即可。3.2 手工干预System.load 绝对路径与它的适用时机有些场景不方便改启动参数比如程序已经被打成 Windows 服务或者启动脚本掌握在运维手里。这时可以用代码直接加载绝对路径public class JacobLoader { static { // 绝对路径加载绕开 java.library.path 的所有搜索逻辑 System.load(D:\\app\\jacob-lib\\jacob-1.20-x64.dll); } public static void main(String[] args) { // 静态块执行完后后续 JACOB 调用会复用这个已加载的库 System.out.println(loaded); } }System.load的参数必须是完整路径而且要带.dll后缀路径里的反斜杠要转义或者用正斜杠D:/app/jacob-lib/jacob-1.20-x64.dll。需要注意这个操作必须发生在 JACOB 任何类被触发之前最稳妥的方式就是放在某个类的static块里并且确保这个类是程序入口第一个加载的类。如果 JACOB 自己已经加载过一次你又手动 load 一次可能抛出 “Native Library already loaded in another classloader” 之类的异常。这个方法适合做兜底不适合当常规手段。能改启动参数时优先用 3.1 的方式。3.3 最小冒烟测试用 FileSystemObject 验证整条链路配置完之后先不要直接跑业务代码。用 Windows 自带的 COM 组件做一次最小冒烟测试验证 JVM、DLL、COM 三层链路全部通import com.jacob.activeX.ActiveXComponent; import com.jacob.com.ComThread; import com.jacob.com.Dispatch; import com.jacob.com.Variant; public class JacobSmokeTest { public static void main(String[] args) { // 初始化当前线程为 STA 模式COM 对象创建前需要这一步 ComThread.InitSTA(); ActiveXComponent fso null; try { // 通过 ProgID 创建 FileSystemObject 实例 fso new ActiveXComponent(Scripting.FileSystemObject); Dispatch fsoObj fso.getObject(); // 调用 COM 方法 GetSpecialFolder(0)0 表示 Windows 目录 Variant winDir Dispatch.call(fsoObj, GetSpecialFolder, new Variant(0)); System.out.println(Windows dir: winDir.getString()); } finally { // 释放 COM 引用计数避免对象堆积 if (fso ! null) { fso.safeRelease(); } // 退出 COM 线程让进程干净结束 ComThread.Release(); } } }这段代码里ComThread.InitSTA()把当前线程初始化为单线程套间JACOB 创建的 COM 对象默认活动在这个套间里。new ActiveXComponent(Scripting.FileSystemObject)通过 ProgID 定位 COM 类Dispatch.call的第一个参数是 COM 对象引用第二个是方法名后面是参数。GetSpecialFolder(0)返回的是 Windows 系统目录的路径Variant#getString()把 COM 的 VARIANT 类型转成 Java String。这个测试如果跑通说明 DLL 位数、java.library.path、COM 组件注册状态都没问题。如果报错直接进第 5 章对照排查。3.4 容器里的配置setenv.bat 注入 library path在 Tomcat 这类 Servlet 容器里启动参数由容器脚本控制。常见做法是在 Tomcat 的bin目录下新建或编辑setenv.batset JAVA_OPTS%JAVA_OPTS% -Djava.library.pathD:\app\jacob-libTomcat 启动时会自动加载setenv.bat把这段参数拼进 JVM 启动命令。放在这里比直接改catalina.bat更干净升级 Tomcat 时不会被覆盖。容器场景下额外要注意线程模型Web 容器的线程池会复用线程不要在请求结束后依赖线程销毁来释放 COM 对象必须像 3.3 那样在业务代码里显式释放。4. 用 jacob 1.20 调用 COM 组件ActiveXComponent、Dispatch 与参数传递DLL 加载成功只是拿到了桥的通行证。真正干活的是ActiveXComponent和Dispatch这两个类。前者负责创建 COM 实例后者负责调用方法、读写属性。这一章讲三个核心问题怎么定位 COM 对象、怎么传参数、怎么释放。4.1 用 ProgID 还是 CLSID 定位 COM 对象JACOB 创建 COM 对象只需要一个字符串这个字符串可以是 ProgID也可以是 CLSID。ProgID 是人类可读的名字比如Scripting.FileSystemObject、WScript.Shell优点是直观、代码可读性好CLSID 是注册表里登记的唯一标识形如{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}优点是绝对不会重名。实际项目中优先用 ProgID因为它不依赖具体的 GUID 记忆。但遇到Class not registered时先不要急着怀疑 JACOB。32 位和 64 位系统各有独立的注册表视图64 位 JVM 只能看到 64 位注册表视图32 位 JVM 只能看到 32 位视图。如果你的 COM 组件是用 32 位安装程序注册的64 位 JVM 去创建它就会报找不到类。这时要么把 JVM 位数和组件位数对齐要么改用组件的 CLSID 试试有时 CLSID 的注册位置和 ProgID 不一致换一种定位方式能绕过问题。4.2 Dispatch.call 的参数规则Variant 包装与方法名大小写调用 COM 方法最通用的写法是Dispatch.call。下面以WScript.Shell为例调用它的ExpandEnvironmentStrings方法展开环境变量import com.jacob.activeX.ActiveXComponent; import com.jacob.com.Dispatch; import com.jacob.com.Variant; // 创建 WScript.Shell 实例 ActiveXComponent shell new ActiveXComponent(WScript.Shell); Dispatch shellObj shell.getObject(); // 调用 ExpandEnvironmentStrings 方法展开 %TEMP% Variant result Dispatch.call(shellObj, ExpandEnvironmentStrings, new Variant(%TEMP%)); System.out.println(result.getString());这里有三个容易踩的点。第一方法名必须和 COM 接口定义完全一致大小写敏感不要按 Java 习惯写成expandEnvironmentStrings。第二参数尽量用Variant显式包装字符串用new Variant(str)整数用new Variant(int)布尔用new Variant(true)。虽然 JACOB 会做隐式转换但某些 COM 方法对参数类型很敏感隐式转换传过去的类型可能不是组件期望的VT_BSTR或VT_I4导致方法调用失败或返回奇怪的结果。第三Dispatch.call的返回值是Variant转成 Java 类型时要用对应的getString()、getInt()、getBoolean()不要直接toString()后者在某些版本里会带上多余的包装信息。4.3 释放与线程模型safeRelease 与 ComThread.Release 必须配套COM 对象的生命周期和 Java 对象完全不同。Java 对象有 GC 兜底COM 对象靠引用计数计数归零才真正释放。JACOB 的ActiveXComponent提供了safeRelease()方法用于显式递减 COM 引用计数。常见错误是只调用new ActiveXComponent(...)不调用safeRelease()结果是程序反复创建 COM 对象进程内存和句柄持续增长。正确的结构是 try/finallyComThread.InitSTA(); ActiveXComponent comp null; try { comp new ActiveXComponent(Scripting.FileSystemObject); // 业务调用可能包含循环 } finally { if (comp ! null) { comp.safeRelease(); } ComThread.Release(); }线程模型上有一条边界要记住COM 对象不能随便跨线程传递。在哪个线程创建的 COM 对象原则上就应该在哪个线程调用。多线程场景下不要多个线程共享同一个ActiveXComponent实例正确做法是每个线程各自InitSTA()、各自创建实例、各自释放。如果组件本身支持 FreeThreaded 模型可以考虑ComThread.InitMTA()但绝大多数业务场景用不到按 STA 处理最稳妥。5. jacob 1.20 落地避坑5 个反复出现的翻车现场与解决办法这一章列的 5 个问题是实际使用 jacob 1.20 时出现频率最高的每个都按“现象、原因、解决”的顺序写可以直接当排查手册用。5.1 x64/x86 DLL 与 JVM 位数不匹配现象程序启动时报UnsatisfiedLinkError错误信息里明确出现 “IA 32-bit” 或 “64-bit platform” 字样指向jacob-1.20-x64.dll或jacob-1.20-x86.dll。原因JVM 位数和 DLL 位数不一致。64 位 JVM 加载 32 位 DLL或者 32 位 JVM 加载 64 位 DLLWindows 加载器直接拒绝。解决用第 2 章的sun.arch.data.model方法确认 JVM 位数换上对应的 DLL。注意检查 IDE 或应用服务器内置的 JRE命令行里的 java 是 64 位不代表 IDE 用的是同一个。这类错误最有迷惑性的地方在于DLL 文件确实存在路径也对唯一的问题是位数不对。5.2 报了 no jacob-1.20-x64 in java.library.path 但文件明明在现象错误信息是no jacob-1.20-x64 in java.library.path但打开目录jacob-1.20-x64.dll就躺在那里。原因文件在但 JVM 搜索的路径不包含这个目录。还有一种隐蔽情况代码里在main开头写了System.setProperty(java.library.path, ...)以为能动态修改搜索路径。这个操作对已启动的 JVM 不一定生效因为本地库搜索逻辑在 JVM 初始化阶段就可能已经读走了这个属性。解决把-Djava.library.path放到 JVM 启动参数里而不是代码里设置属性。改不了启动参数就用System.load绝对路径。另外确认库名拼写JACOB 加载时用的库名是jacob-1.20-x64对应的文件必须是jacob-1.20-x64.dll一个字符都不能差。5.3 加载 DLL 成功第一次调用就报 The specified module could not be found现象DLL 加载阶段没报错但创建 COM 对象或调用方法时抛UnsatisfiedLinkError附带信息是 “The specified module could not be found”。文件明明在路径也对。原因jacob-1.20-x64.dll本身依赖了 VC 运行库目标机器上没装。很多精简的 Windows Server 环境默认没有完整的运行库DLL 能加载但缺少依赖项。这种情况和 JACOB 自身配置无关属于本地库依赖缺失。解决在目标机器上安装对应版本的 VC Redistributable。1.20 这个年代的本土库通常依赖较早的编译工具链安装时把常见几个版本都装上是省心的做法。如果确实装不了运行库也可以把缺失的msvc*.dll放到 JACOB DLL 同目录但这个做法污染环境只建议在受限环境临时用。5.4 实例化 COM 组件报 Class not registered 或 Access is denied现象new ActiveXComponent(某组件)时抛Class not registered或者创建成功但调用时抛Access is denied。原因Class not registered通常是这个 COM 组件根本没在当前注册表视图里登记或者组件本身没安装。Access is denied则是权限问题Java 进程以普通用户运行而目标 COM 组件要求更高的权限或者 DCOM 配置里的身份设置不允许当前用户启动。解决Class not registered先确认组件装了没有、位数对不对必要时用regsvr32重新注册。这里注意注册的对象是你调用的那个 COM 组件不是jacob-1.20-x64.dllJACOB 的 DLL 不需要注册。Access is denied则先尝试以管理员身份运行进程如果是服务型 COM需要打开组件服务管理工具找到对应组件把“身份”选项卡改成当前登录用户或交互式用户。5.5 程序退出了javaw.exe 还卡在进程列表里现象Java 程序正常执行完控制台都关了但javaw.exe进程还在杀也杀不掉或者第二次启动时提示 DLL 文件被占用。原因COM 对象的引用计数没有归零或者 STA 线程没有被释放。ComThread.InitSTA()创建了 COM 线程但代码里没有对应的ComThread.Release()线程就一直挂着。解决把释放逻辑写进finally块先safeRelease()释放所有创建的ActiveXComponent再调用ComThread.Release()。如果业务代码里有分支提前return务必保证 finally 里的释放逻辑不被跳过。排查时可以逐个注释业务调用定位是哪个 COM 对象没释放。6. 验证 jacob-1.20-x64.dll 是否真正生效PE 头检查与最小验证习惯DLL 加载成功不等于万事大吉。最后一章讲一个能彻底确认 DLL 位数的验证方法以及一个我养成的部署习惯。6.1 用 PowerShell 读 PE 头确认 DLL 的真实位数文件名写着 x64 不一定真的是 x64拷文件时搞错、重命名错位都有可能。要确凿验证直接读 DLL 的 PE 头看 Machine 字段$path jacob-1.20-x64.dll $bytes [System.IO.File]::ReadAllBytes($path) $peOffset [BitConverter]::ToInt32($bytes, 0x3C) $machine [BitConverter]::ToUInt16($bytes, $peOffset 4) switch ($machine) { 0x8664 { x64; break } 0x014c { x86; break } default { unknown machine: 0x{0:X} -f $machine } }原理是DOS 头偏移0x3C处存放了一个 4 字节值指向 PE 头的起始位置PE 头起始后偏移 4 字节处是 Machine 字段。0x8664表示 AMD64 架构也就是 x640x014c表示 i386也就是 x86。这段脚本不需要额外工具Windows 上 PowerShell 直接跑。比看文件属性、看文件名都可靠。6.2 每台目标机器先跑冒烟测试再进业务我的习惯是任何一台新机器、新 JDK、新服务器部署 JACOB 相关代码前先跑第 3 章的JacobSmokeTest那个最小 demo。它只做三件事初始化 COM、创建 FileSystemObject、调用一个方法。跑通了说明 JVM 位数、DLL 位数、COM 组件注册状态三层全部正常跑不通错误信息会把问题指向其中一层。这个习惯帮我省过很多次排查时间。JACOB 的问题是全局性的DLL 一旦没加载对业务代码里所有 COM 调用都会跟着崩而且错误信息往往在几层调用之后才出现追起来非常难受。先花两分钟跑冒烟测试确认底座没问题再进业务功能是这套方案里性价比最高的做法。希望帮到你。本文还有配套的精品资源点击获取
