如何设置IronPdfEngine
IronPdfEngine是一个gRPC服务器，执行每个PDF操作——创建、编辑、阅读和渲染。 IronPDF for Java库是此服务器的API包装器：当您的Java代码调用任何IronPDF方法时，IronPdfEngine执行工作。 默认情况下，IronPDF for Java将IronPdfEngine作为本地子进程生成，并自动管理其生命周期。 对于更高级的部署——共享微服务，Docker容器或气隙网络——您可以将IronPdfEngine作为独立的远程服务器运行。
快速入门：设置IronPdfEngine for Java
如何设置IronPdfEngine for Java
- 将IronPDF依赖项添加到您的
pom.xml文件中 - 选择本地模式：运行时下载或捆绑依赖项
- 对于远程模式，使用
setIronPdfEngineHost配置主机地址 - 对于远程模式，使用
setIronPdfEnginePort配置端口 - 调用任何IronPDF渲染方法——IronPdfEngine处理PDF工作
Settings.getIronPdfEngineVersion()来确认所需版本。您应该使用哪个部署模式？
IronPdfEngine支持两种部署方法：本地和远程。 选择它们取决于您的应用程序的架构。
本地模式 (默认为选项) 是独立应用程序、桌面工具和单服务器部署的正确选择。 IronPDF for Java自动将IronPdfEngine作为子进程启动——不需要单独的基础设施。 在本地模式下，有两种获取IronPdfEngine的二进制文件的方法：首次运行时下载或将其捆绑为Maven依赖项。
远程模式适合分布式系统，在这些系统中，一个IronPdfEngine实例可以为多个应用节点服务。 它也是Docker部署、Kubernetes容器、无法在运行时下载二进制文件的气隙网络以及在中心化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（苹果硅）
//: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-engine-xxx-xxx依赖版本必须完全匹配。 版本字符串是指IronPDF for Java的发行版，而不是IronPdfEngine的内部版本号。| 优点 | 限制 |
|---|---|
| 启动速度更快——无需下载步骤 | 较大的应用程序包 |
| 安装后无需访问互联网 | 必须显式指定目标平台 |
| 在气隙环境中保持一致的行为 | 安装多个平台工件会显著增加构建大小 |
如何连接到远程IronPdfEngine？
远程模式允许多个应用实例通过gRPC共享一个IronPdfEngine服务器。 这是在微服务架构、容器化部署和PDF处理中心化的环境中常见的。
如何验证所需的IronPdfEngine版本？
版本匹配严格——IronPDF for Java 2024.2.2需要IronPdfEngine 2024.2.2。 在部署服务器之前，使用getIronPdfEngineVersion确认所需的版本：
:path=/static-assets/ironpdf-java/content-code-examples/get-started/use-ironpdfengine-8.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=/static-assets/ironpdf-java/content-code-examples/get-started/use-ironpdfengine-9.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调用都路由到远程服务器。 没有启动本地IronPdfEngine子过程，也不需要在您的pom.xml中平台特定的引擎依赖。
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是一个执行所有PDF操作的gRPC服务器 — 创建、编辑、读取和渲染。IronPDF for Java是一个围绕此服务器的API包装器，因此每个Java方法调用都由IronPdfEngine处理，没有它，Java库无法执行任何PDF工作。
本地和远程IronPdfEngine有何不同?
本地模式在与您的Java应用程序相同的机器上启动IronPdfEngine作为子进程 — 无需额外基础设施。远程模式连接到通过gRPC的独立IronPdfEngine服务器，适合微服务、Docker部署和共享的PDF处理节点。
何时应使用远程IronPdfEngine代替本地？
当您需要多个应用实例共享一个PDF处理服务器时，部署在Kubernetes或Docker Compose环境中，或者在气隙网络中无法在运行时下载二进制文件时使用远程IronPdfEngine。
如何在Java中配置远程IronPdfEngine连接？
在应用启动时使用服务器IP或主机名调用Settings.setIronPdfEngineHost()，并使用端口号调用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二进制文件。下载后，不再需要互联网访问。如果添加捆绑平台依赖或使用远程模式，则在任何时候都不需要互联网访问。
How do I detect and recover from a dead IronPdfEngine in Java?
Call IronPdfEngineManager.isEngineActive() to check whether the engine is connected, then IronPdfEngineManager.restartEngine() to force a clean reconnect if it is not. This watchdog pattern lets long-running services recover automatically when the engine is interrupted by a host restart, an operating system kill, or a native crash. It is an advanced feature; most applications rely on the automatic lifecycle and never call it.
Can I restart IronPdfEngine when using a custom gRPC connection?
No. In CUSTOM connection mode (a channel passed to IronPdfEngineConnection.withCustomGrpcConnection), stopEngine() and restartEngine() throw UnsupportedOperationException because the caller owns the channel and IronPDF cannot rebuild it. isEngineActive() and startEngine() still work in every connection mode.
还在滚动吗？
想快速获得证据？
运行示例看着你的HTML代码变成PDF文件。
免费开始
免费开始
预定免费现场演示
