IronPdfEngine 從 Fat JAR 的連接失敗

Updated: 2026年7月3日

當您的 IronPDF for Java 應用程式打包為 fat (uber) JAR 時，客戶端無法連接到內部渲染引擎。IronPdfEngine 啟動並在正確的端口上監聽，但 Java 客戶端進行20次連接嘗試，每次都失敗。

Failed to connect to IronPdfEngine after 20 attempts

Failed to connect to IronPdfEngine after 20 attempts

Text

失敗原因來自將每個依賴項合併到一個自組裝的遮蔽 (uber) JAR 中，例如使用 Maven Shade 或 Gradle Shadow 插件。合併依賴項的重疊資源文件阻止 Java 客戶端到達 IronPdfEngine 子進程：引擎啟動並打開預期的端口，但客戶端始終無法連接，並在20次重試後放棄。保持每個依賴項為類路徑上的單獨文件可以避免衝突。

解決方案

正常構建專案，將其依賴項複製到文件夾中，然後不使用 java -jar 而是直接將 Java 指向這些文件來啟動應用程式。

1. 構建專案

mvn clean package

mvn clean package

SHELL

2. 複製運行時依賴項

將每個庫置於 target/libs 中作為單獨的 JAR，這是類路徑方法所需要的：

mvn dependency:copy-dependencies -DoutputDirectory=target/libs

mvn dependency:copy-dependencies -DoutputDirectory=target/libs

SHELL

3. 從類路徑運行

從展開的類路徑而非 fat JAR 啟動應用程式。將 com.example.Main 替換為您的實際主類。

Windows：

java --add-opens java.base/java.nio=ALL-UNNAMED -cp "target/classes;target/libs/*" com.example.Main

java --add-opens java.base/java.nio=ALL-UNNAMED -cp "target/classes;target/libs/*" com.example.Main

SHELL

Linux / macOS:

java --add-opens java.base/java.nio=ALL-UNNAMED -cp "target/classes:target/libs/*" com.example.Main

java --add-opens java.base/java.nio=ALL-UNNAMED -cp "target/classes:target/libs/*" com.example.Main

SHELL

兩個命令之間唯一的差別是類路徑分隔符：Windows 上為分號 (;)，Linux 和 macOS 上為冒號 (:)。

除錯提示

**無效的方法：**從 fat JAR 運行成功啟動 IronPdfEngine，但 Java 客戶端始終無法連接。
**--add-opens 本身不足以解決問題：**即便在運行 fat JAR 時新增 JVM 標誌，仍然無法修復連接失敗。該標誌僅在上述類路徑啟動時有效。
**PDF/A 版本字串：**如果您的程式碼將 PDF/A 版本作為字串參數傳遞，請使用 PdfA2a，而不是 PdfAVersions.PdfA2a。

立即與工程團隊聊天

技術作家

Curtis Chau擁有Carleton大學的電腦科學學士學位，專精於前端開發，擁有Node.js、TypeScript、JavaScript和React的專業知識。Curtis熱衷於建立直觀且美觀的使用者介面，喜愛使用現代框架並建立結構良好、視覺吸引力的手冊。

...

準備好開始了嗎？

版本：2026.6剛剛發布

免費 Maven 下載

using Maven 安裝

版本： 2026.6

<dependency>
   <groupId>com.ironsoftware</groupId>
   <artifactId>ironpdf</artifactId>
   <version>2026.6.1</version>
</dependency>

https://central.sonatype.com/artifact/com.ironsoftware/ironpdf/2026.6.1

or

Java PDF JAR

下載 JAR

版本： 2026.6

手動安裝到您的專案中