IronPdfEngine 是一個 gRPC 伺服器，可執行所有 PDF 操作——包括建立、編輯、讀取及渲染。 IronPDF for Java 函式庫是圍繞此伺服器的 API 封裝：當您的 Java 程式碼呼叫任何 IronPDF 方法時，IronPdfEngine 便會執行相關作業。 預設情況下，IronPDF for Java 會將 IronPdfEngine 作為本地子程序啟動，並自動管理其生命週期。 若需進行更進階的部署（例如共用微服務、Docker 容器或物理隔離網路），您亦可將 IronPdfEngine 作為獨立的遠端伺服器來運行。
快速入門：設定 Java 版的 IronPdfEngine
如何在 Java 中設定 IronPdfEngine
- 請將 IronPDF 依賴項新增至您的
pom.xml檔案中 - 選擇本地化模式：執行時下載或內建依賴項
- 若採用遠端模式，請使用
setIronPdfEngineHost來設定主機位址 - 若採用遠端模式，請使用
setIronPdfEnginePort來設定連接埠 - 呼叫任何 IronPDF 渲染方法 — IronPdfEngine 負責處理 PDF 相關工作
Settings.getIronPdfEngineVersion() 確認所需版本。）]您應該選擇哪種部署模式？
IronPdfEngine 支援兩種部署方式：本地部署與遠端部署。 選擇哪一種取決於您的應用程式架構。
"本地模式"（預設模式）是獨立應用程式、桌面工具及單伺服器部署的理想選擇。 IronPDF for Java 會自動將 IronPdfEngine 作為子程序啟動 — 無需額外基礎架構。 在本地模式下，有兩種方式可取得 IronPdfEngine 二進位檔：首次執行時下載，或將其打包為 Maven 依賴項。
遠端模式適用於分散式系統，其中單一 IronPdfEngine 實例可服務多個應用程式節點。 這也是基於 Docker 的部署、Kubernetes Pod、無法在執行時下載二進位檔的隔離網路，以及任何透過集中化 PDF 處理來降低各服務開銷情境下的首選方案。
以下各節將詳細說明這兩種模式。
如何設定本地 IronPdfEngine？
在本地執行 IronPdfEngine 有兩種方式。 兩者產生相同的執行時行為——差異在於引擎二進位檔何時以及如何抵達目標機器。
選項 1：在執行階段下載 IronPdfEngine
預設情況下，在新增核心 ironpdf 依賴項後，IronPDF 會在首次執行時偵測主機平台（例如 Windows x64 或 Linux x64），並從網際網路下載相應的 IronPdfEngine 二進位檔。
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf</artifactId>
<version>20xx.xx.xx</version>
</dependency>//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf</artifactId>
<version>20xx.xx.xx</version>
</dependency>初次下載後，二進位檔會被快取於本地端，後續執行時無需進行網路呼叫。
| 優勢 | 限制 |
|---|---|
| 最小的應用程式套件大小 | 首次執行時需連線至網際網路 |
| 支援從單一建置產物部署至多個目標平台 | 下載二進位檔時，首次啟動速度較慢 |
選項 2：將 IronPdfEngine 作為依賴項打包（建議）
IronPDF Java 提供平台專用的 Maven 套件，將 IronPdfEngine 作為 .zip 檔案封裝於依賴項中。 該函式庫會自動擷取並使用該資料——執行時無需進行網路呼叫。
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>接著為您的目標環境添加平台構建產物。 請僅安裝您目標平台對應的套件 — 每個套件體積龐大，若全部安裝將不必要地增加建置大小。
Windows x64
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-windows-x64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-windows-x64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>Windows x86
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-windows-x86</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-windows-x86</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>Linux x64
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-linux-x64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-linux-x64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>macOS x64
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-macos-x64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-macos-x64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>macOS ARM (Apple Silicon)
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-macos-arm64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-macos-arm64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>ironpdf 與 ironpdf-engine-xxx-xxx 的依賴項版本必須完全一致。 （版本字串指的是 IronPDF for Java 的發行版本，而非 IronPdfEngine 的內部版本號。）}]| 優勢 | 限制 |
|---|---|
| 啟動更快速 — 無需下載步驟 | 較大的應用程式套件 |
| 安裝後無需網路連線 | 必須明確指定目標平台 |
| 在氣隙環境中保持一致的運作行為 | 安裝多個平台構建產物會顯著增加建置大小 |
如何連線至遠端的 IronPdfEngine？
遠端模式允許多個應用程式執行個體透過 gRPC 共用單一 IronPdfEngine 伺服器。 這在微服務架構、容器化部署以及 PDF 處理集中化的環境中相當常見。
如何驗證所需的 IronPdfEngine 版本？
版本相容性要求嚴格 — IronPDF for Java 2024.2.2 必須與 IronPdfEngine 2024.2.2 完全對應。 請使用 getIronPdfEngineVersion 確認所需版本，再部署伺服器：
//:path=Main.java
// Retrieve the IronPdfEngine version required by this Java library build
String ironPdfEngineVersion = Settings.getIronPdfEngineVersion();
System.out.println("Required IronPdfEngine version: " + ironPdfEngineVersion);//:path=Main.java
// Retrieve the IronPdfEngine version required by this Java library build
String ironPdfEngineVersion = Settings.getIronPdfEngineVersion();
System.out.println("Required IronPdfEngine version: " + ironPdfEngineVersion);部署或拉取與回傳版本字串相符的 IronPdfEngine Docker 映像檔或二進位檔。
如何設定遠端連線？
假設 IronPdfEngine 正在 123.456.7.8:33350 處執行。 在呼叫任何 IronPDF 方法之前，請先設定主機與埠號。 最佳實務是在應用程式啟動時，於執行任何 PDF 操作之前，呼叫這些函式：
//:path=Main.java
// Configure IronPDF for Java to connect to a remote IronPdfEngine instance
com.ironsoftware.ironpdf.Settings.setIronPdfEngineHost("123.456.7.8");
com.ironsoftware.ironpdf.Settings.setIronPdfEnginePort(33350);//:path=Main.java
// Configure IronPDF for Java to connect to a remote IronPdfEngine instance
com.ironsoftware.ironpdf.Settings.setIronPdfEngineHost("123.456.7.8");
com.ironsoftware.ironpdf.Settings.setIronPdfEnginePort(33350);執行這兩行程式碼後，應用程式中後續的所有 IronPDF 呼叫都會轉由遠端伺服器處理。 您的 pom.xml 不會啟動任何 IronPdfEngine 的本地子程序，亦無需依賴任何特定平台的引擎。
33350 埠號。完整的遠端設定流程是怎樣的？
以下範例連線至遠端 IronPdfEngine 實例，並將 HTML 字串渲染為 PDF 檔案——此 API 與本地模式相同，僅配置設定有所不同：
//:path=Main.java
import com.ironsoftware.ironpdf.*;
public class Main {
public static void main(String[] args) throws Exception {
// Point the library to the remote IronPdfEngine server
Settings.setIronPdfEngineHost("123.456.7.8");
Settings.setIronPdfEnginePort(33350);
// Render HTML to PDF — IronPdfEngine on the remote host performs the work
PdfDocument pdf = PdfDocument.renderHtmlAsPdf("<h1>Hello from remote IronPdfEngine</h1>");
pdf.saveAs("output.pdf");
}
}//:path=Main.java
import com.ironsoftware.ironpdf.*;
public class Main {
public static void main(String[] args) throws Exception {
// Point the library to the remote IronPdfEngine server
Settings.setIronPdfEngineHost("123.456.7.8");
Settings.setIronPdfEnginePort(33350);
// Render HTML to PDF — IronPdfEngine on the remote host performs the work
PdfDocument pdf = PdfDocument.renderHtmlAsPdf("<h1>Hello from remote IronPdfEngine</h1>");
pdf.saveAs("output.pdf");
}
}渲染後的 PDF 會透過 gRPC 傳回給 Java 程序，並儲存至本地端。 遠端伺服器負責處理所有基於 Chrome 的渲染、字型載入及資源解析。
接下來該怎麼做？
完成 IronPdfEngine 的設定後，即可使用完整的 IronPDF for Java 功能集——包括 HTML 轉 PDF、PDF 編輯、合併、加蓋水印等。
- 開始在 Java 中將 HTML 轉為 PDF — 針對最常見轉換情境的逐步範例
- 探索 IronPDF for Java 教學指南 — 深入解析浮水印、頁首與頁尾、表單及數位簽章的詳細指南
- 下載 IronPDF for Java 並開始免費試用 — 功能完整的試用版，開發用途無時間限制
- 購買生產環境部署授權 — 提供永久授權與訂閱方案，並可取得原始碼
常見問題
什麼是 IronPdfEngine？為什麼 IronPDF for Java 需要它？
IronPdfEngine 是一個 gRPC 伺服器，負責執行所有 PDF 操作——包括建立、編輯、讀取及渲染。IronPDF for Java 是圍繞此伺服器建構的 API 封裝層，因此每個 Java 方法呼叫皆由 IronPdfEngine 處理。若缺少此元件，Java 函式庫將無法執行任何 PDF 相關作業。
本地版與遠端版 IronPdfEngine 有何區別？
本地模式會在您的 Java 應用程式所在的同一台機器上，以子程序形式啟動 IronPdfEngine —— 無需額外基礎架構。遠端模式則透過 gRPC 連線至獨立的 IronPdfEngine 伺服器，此模式適用於微服務、Docker 部署以及共用 PDF 處理節點。
何時應使用遠端 IronPdfEngine 而非本地版本？
當您需要多個應用程式實例共用同一台 PDF 處理伺服器、在 Kubernetes 或 Docker Compose 環境中部署，或在無法於執行時下載二進位檔的氣隙環境中運行時，請使用遠端 IronPdfEngine。
如何在 Java 中設定 IronPdfEngine 的遠端連線？
在應用程式啟動時，請先呼叫 Settings.setIronPdfEngineHost() 並傳入伺服器 IP 或主機名稱，以及呼叫 Settings.setIronPdfEnginePort() 並傳入連接埠號碼，再呼叫任何 IronPDF 方法。IronPdfEngine 的預設連接埠為 33350。
我該使用哪個 Maven 工件來將 IronPdfEngine 打包為依賴項？
請根據您的部署目標，添加對應的特定平台套件 — 例如，Linux 伺服器使用 ironpdf-engine-linux-x64，Windows 則使用 ironpdf-engine-windows-x64。套件版本必須與 IronPDF 核心依賴項的版本完全一致。
如何確認我的 Java 函式庫需要哪個 IronPdfEngine 版本？
請在您的 Java 程式碼中呼叫 Settings.getIronPdfEngineVersion()。此方法會傳回確切的版本字串，該字串必須與您部署的 IronPdfEngine 二進位檔或 Docker 映像檔相符。
我可以在一個專案中安裝多個平台引擎的依賴項嗎？
從技術上來說是可行的，但每個套件體積龐大，若安裝多個套件會不必要地增加建置規模。請僅安裝與您的目標部署平台相符的套件。
使用 IronPDF for Java 是否需要網路連線？
僅當您使用「運行時下載」選項時（pom.xml 中不包含特定平台的依賴項）。首次執行時，IronPDF 會為您的平台下載 IronPdfEngine 二進位檔。下載完成後，便不再需要網路連線。若您加入內建的平台依賴項或使用遠端模式，則全程皆無需網路連線。
還在捲動嗎？
想要快速證明？
執行範例 觀看您的 HTML 變成 PDF。
立即免費開始
立即免費開始
預約免費線上示範
無需信用卡或註冊帳號
