IRONSOFTWAREHOME
IRONSUITE所有10的价格为2
联系销售
按公司
加入我们的专家网络

如何在AWS上设置IronPDF for Java

Curtis Chau
Curtis Chau
Updated: 2026年9月17日

本指南介绍了如何在AWS Lambda上使用Docker和AWS SAM部署IronPDF for Java。 由于IronPDF依赖于基于Chrome的原生渲染引擎，因此它不能在标准Zip部署的Lambda函数上运行——Docker是唯一支持的部署模型。 以下步骤涵盖了一切，从安装所需工具、配置pom.xml依赖项、编写Lambda处理程序，到构建容器镜像并使用SAM CLI部署。

快速入门：在AWS Lambda上部署IronPDF for Java

Start using IronPDF in your project today with a free trial.

第一步：
arrow pointer

目录

需求条件是什么？

在开始之前，请确认在开发机器上安装了以下工具。每个工具在构建和部署流水线上扮演特定角色。

  • IntelliJ IDEA - 本指南使用的IDE。下载链接：jetbrains.com/idea。
  • AWS Toolkit for JetBrains - 提供SAM项目向导和Lambda运行配置在IntelliJ中。 设置说明在AWS Toolkit for JetBrains文档页面。
  • AWS SAM CLI - 构建Docker镜像并部署Lambda函数的命令行工具。 通过SAM CLI安装指南进行安装。
  • Docker Desktop - 必需的，因为Lambda函数被打包为容器镜像，而不是一个Zip存档。下载Docker社区版。

在部署到AWS之前进行本地调用测试，也请安装：

一旦所有工具到位，打开IntelliJ IDEA并通过File → New → Project创建一个新项目。 在项目向导中，选择AWS Lambda模板并选择以下选项：

  • 包类型：Image
  • 运行时：java11
  • SAM模板：Maven

在IntelliJ IDEA中创建AWS Lambda项目并选择图像包类型

AWS Lambda配置屏幕显示java8运行时和Maven SAM模板

为什么必须使用Docker而不是Zip部署？

AWS Lambda支持两种部署包类型：Zip存档和容器镜像。 Zip部署非常适合轻量级的Java函数，因为运行时环境完全由AWS管理。 然而，IronPDF提供了一个本机二进制文件 —— 基于Chrome的PDF渲染引擎 —— 必须在运行时提取并执行。Zip部署的Lambda执行环境限制文件系统写入到/tmp，并且Zip包层的限制阻止了大型本机二进制文件的提取。

容器镜像部署消除了这些限制。 当您定义自己的Docker镜像时，您可以控制基础操作系统、已安装的系统包和目录布局。 IronPDF的渲染引擎可以在启动时提取到/tmp，所需的系统库可以预先安装在镜像中，并且容器大小限制（10 GB）足够大，可以容纳完整的引擎。

实际的后果很简单：在PackageType: Image并使用支持Docker的基础镜像构建。 SAM CLI将处理剩下的部分。

如何配置Maven依赖？

pom.xml文件需要标准Lambda SDK以外的三类附加依赖项：IronPDF Java库、IronPDF Linux x64渲染引擎和IronPDF引擎内部使用的gRPC传输。

打开<dependencies>内添加以下依赖项：

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-linux-x64</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.3</version>
</dependency>
<dependency>
    <groupId>io.perfmark</groupId>
    <artifactId>perfmark-api</artifactId>
    <version>0.26.0</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-okhttp</artifactId>
    <version>1.50.2</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-netty-shaded</artifactId>
    <version>1.50.2</version>
</dependency>
XML

ironpdf-engine-linux-x64工件捆绑了基于Chromium的预编译渲染引擎用于64位Linux。 这就是允许IronPDF在Lambda容器内将HTML渲染为PDF的原因。 没有它，渲染调用将因为缺少二进制文件而失败。 gRPC依赖项(perfmark-api)是必需的，因为IronPDF通过本地gRPC通道与其渲染引擎通信。 slf4j-simple依赖项提供了一个最小的日志记录实现，以便IronPDF的内部日志在CloudWatch中可见。

始终对齐ironpdf-engine-linux-x64版本号——混合版本将导致启动失败。 查看Maven Central上的IronPDF for Java以获取最新版本的字符串。

如何编写Lambda处理程序？

Lambda处理程序类接收APIGatewayProxyResponseEvent。 在第一次渲染操作之前，必须出现两个IronPDF配置调用：将工作目录设置为/tmp并可选启用调试日志记录。

用以下内容替换App.java的内容：

//:path=App.java
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.Settings;

import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;

public class App {
    public APIGatewayProxyResponseEvent handleRequest(
            final APIGatewayProxyRequestEvent input,
            final Context context) {

        APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent();

        // IronPDF must write its engine binaries and temporary files to /tmp.
        // This is the only writable path available in the Lambda execution environment.
        Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));

        // Enable debug logging to CloudWatch during initial testing.
        Settings.setDebug(true);

        try {
            context.getLogger().log("Starting PDF render");

            // Render a PDF from a live URL. Replace with your own HTML or URL as needed.
            PdfDocument pdf = PdfDocument.renderUrlAsPdf("https://www.google.com");

            context.getLogger().log("PDF render complete");

            // Save the rendered PDF to /tmp. Files in /tmp persist for the lifetime
            // of the Lambda execution environment (warm instance).
            pdf.saveAs("/tmp/output.pdf");

            Map<String, String> headers = new HashMap<>();
            headers.put("Content-Type", "application/json");

            return response
                    .withStatusCode(200)
                    .withHeaders(headers)
                    .withBody("PDF generated successfully.");

        } catch (Exception e) {
            context.getLogger().log("PDF render failed: " + e.getMessage());
            return response
                    .withStatusCode(500)
                    .withBody("{\"error\": \"" + e.getMessage() + "\"}");
        }
    }
}
Java

调用Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"))是强制性的。 AWS Lambda的执行环境将函数代码挂载在只读目录中。 IronPDF引擎必须在启动时解压缩支持文件并创建套接字——这些活动需要写访问权限。 /tmp目录是Lambda允许文件写入的唯一位置，因此必须在开始任何渲染之前将IronPDF指向那里。 如果省略此设置， 引擎将无法启动，每次渲染调用都会抛出异常。

对/tmp文件系统中。 如果Lambda函数需要以二进制响应返回PDF或将其上传到S3，请使用pdf.getBinaryData()检索字节，而不是写入磁盘。 对于大型工作负载，上传到Amazon S3并返回预签名URL是推荐的模式。

如何配置SAM模板？

template.yaml文件控制Lambda函数的资源分配。 三个设置直接影响IronPDF是否成功运行：EphemeralStorage.Size。

按照以下方式更新Globals部分：

//:path=template.yaml
Globals:
  Function:
    Timeout: 400
    MemorySize: 2048
    EphemeralStorage:
      Size: 1024
Text

超时时间设置为400秒。 在冷启动时，IronPDF必须将渲染引擎提取到/tmp并启动本地Chromium进程。 在第一次调用上，这个解压过程可能需要30到60秒。 超时时间短于330秒将导致冷启动调用失败并出现任务超时错误。 温启动调用速度更快——简单的HTML转PDF转换通常在5秒内完成。

内存大小设置为2048 MB。 Chromium渲染器需要大量内存。AWS Lambda的IronPDF最低可行内存为1024 MB，但2048 MB降低了内存不足失败的风险，对于复杂页面还提供明显更快的渲染时间，因为Lambda还会根据内存比例调整CPU分配。

临时存储大小设置为1024 MB。 默认的Lambda /tmp分配是512 MB。 IronPDF将渲染引擎二进制文件、字体缓存和临时渲染文件写入/tmp。 这些资源在冷启动时可能超过512 MB，导致引擎解压失败。 将临时存储设置为至少1024 MB可以防止此失败模式。

如何构建Dockerfile？

Dockerfile是这个部署的核心。 它执行多阶段构建：第一阶段使用Maven构建镜像编译Java项目； 第二阶段基于Amazon Linux 2创建最终的Lambda运行时镜像，安装IronPDF的Chromium引擎所需的系统包，并复制编译的工件。

打开项目的Dockerfile并用以下内容替换其内容：

//:path=Dockerfile
# Stage 1: Build the Maven project
FROM public.ecr.aws/sam/build-java8.al2:latest AS build-image
WORKDIR /task
COPY src/src/
COPY pom.xml ./
RUN mvn -q clean install
RUN mvn dependency:copy-dependencies -DincludeScope=compile

# Stage 2: Create the Lambda runtime image
FROM public.ecr.aws/lambda/java:8.al2

# Update the package index and install system libraries required by Chromium.
# These packages provide font rendering, graphics, audio, GTK3, and input
# method support — all needed by the headless browser inside IronPDF.
RUN yum update -y && \
    yum install -y \
        pango.x86_64 \
        libXcomposite.x86_64 \
        libXcursor.x86_64 \
        libXdamage.x86_64 \
        libXext.x86_64 \
        libXi.x86_64 \
        libXtst.x86_64 \
        cups-libs.x86_64 \
        libXScrnSaver.x86_64 \
        libXrandr.x86_64 \
        GConf2.x86_64 \
        alsa-lib.x86_64 \
        atk.x86_64 \
        gtk3.x86_64 \
        ipa-gothic-fonts \
        xorg-x11-fonts-100dpi \
        xorg-x11-fonts-75dpi \
        xorg-x11-utils \
        xorg-x11-fonts-cyrillic \
        xorg-x11-fonts-Type1 \
        xorg-x11-fonts-misc \
        glibc-devel.x86_64 \
        at-spi2-atk.x86_64 \
        mesa-libgbm.x86_64 \
        libxkbcommon \
        amazon-linux-extras && \
    amazon-linux-extras install epel -y && \
    yum install -y libgdiplus

# Ensure /tmp is writable by the Lambda execution user.
RUN chmod 777 /tmp/

# Copy the compiled classes and dependencies from the build stage.
COPY --from=build-image /task/target/classes /var/task/
COPY --from=build-image /task/target/dependency /var/task/lib

# Entry point: package.ClassName::methodName
CMD ["helloworld.App::handleRequest"]
Text

两个阶段的基础镜像使用java8。 .al2后缀指示亚马逊Linux 2，这是IronPDF所需的。 旧的java8镜像运行在原始Amazon Linux 1上，它使用不再更新的yum存储库，并且缺少IronPDF依赖的几个软件包。 在使用Java 8部署IronPDF时始终使用.al2镜像。

yum install块安装Chromium渲染页面所需的X11、GTK3、Pango和字体相关的库。 遗漏任何此类包可能会导致PDF输出不完整或渲染引擎因缺少共享库错误而崩溃。 libgdiplus包用于GDI+兼容性，部分IronPDF绘图操作使用。

更新helloworld.App不同。

如何构建和部署Lambda函数？

在Dockerfile、App.java都配置好后，从项目根目录运行以下两个SAM CLI命令。

步骤1 - 构建容器镜像：

//:path=build.sh
sam build -u
SHELL

-u标志指示SAM使用Docker（"使用容器"模式）。 SAM执行多阶段Dockerfile，编译Maven项目并生成最终的Lambda镜像。 预计首次运行时这个步骤需要几分钟，因为Docker会拉取基础镜像。

步骤2 - 部署到AWS：

//:path=deploy.sh
sam deploy --guided
SHELL

--guided标志启动交互式提示，询问堆栈名称、AWS区域、用于工件的S3桶以及是否在部署前确认更改集。 回答提示，SAM会将容器图像推送到Amazon ECR，并创建在template.yaml中定义的Lambda函数、API Gateway和IAM角色。

部署完成后，SAM CLI将输出API端点URL。 打开AWS Lambda Console以查看已部署的函数、运行测试调用以及检查用于IronPDF调试输出的CloudWatch日志。

在第一次调用（冷启动）时，由于Lambda执行环境的启动和IronPDF提取其渲染引擎到/tmp，响应时间预计为60-120秒。 在同一个温实例上随后的调用将在几秒内返回。 如果生产工作负荷中冷启动延迟是一个问题，考虑使用Lambda预置并发来保持实例温暖。

您还可以通过运行sam local invoke以及一个测试事件负载在本地测试函数，前提是Docker在开发机上运行。

下一步是什么？

Lambda函数现已部署并正在渲染PDF。 接下来的指南涵盖了成功部署IronPDF后的最常见的下一步操作：

启动IronPDF for Java免费试用，在评估期间在Lambda函数中无限制地生成和编辑PDF。 准备好部署到生产环境时，查看IronPDF许可选项以找到适合您无服务器工作负载的计划。

常见问题解答

为什么我不能在AWS Lambda上使用Zip部署IronPDF？

IronPDF附带一个基于Chromium的本地渲染引擎，必须在运行时提取并执行。Zip部署运行在受管理的运行时环境中，限制了写权限并限制了包大小。容器镜像部署提供了对文件系统、已安装系统库和镜像大小的完全控制，而IronPDF需要这些。

为什么必须将IronPDF引擎工作目录设置为/tmp/？

Lambda执行环境将函数代码目录挂载为只读。IronPDF必须将其引擎二进制文件、套接字文件和临时渲染资产写入可写位置。在Lambda函数中唯一可写的路径是/tmp/，因此在进行任何渲染操作之前必须调用Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"))。

Lambda函数最少应该有多少内存？

将MemorySize设置为至少1024 MB。Chromium渲染器占用大量内存，较少内存的函数会遇到内存不足错误。对于生产工作负载，建议使用2048 MB，因为AWS还会根据内存比例缩放CPU分配，从而减少渲染时间。

为什么EphemeralStorage大小设置为1024 MB？

默认的Lambda临时存储分配为512 MB。在冷启动时，IronPDF将渲染引擎二进制文件和字体缓存提取到/tmp/。这些资产可能超过512 MB，导致提取失败。将EphemeralStorage设置为1024 MB可以防止此类失败。

为什么使用java8.al2基础镜像而不是java8？

java8基础镜像运行在原始的Amazon Linux 1上，它的包库已经过时，并且缺少IronPDF所需的几个库。java8.al2镜像使用Amazon Linux 2，它包含当前的软件包，并完全支持Chromium渲染器所需的X11、GTK3和Pango库。

IronPDF需要的Lambda超时时间是多少？

将超时时间设置为至少330秒。在冷启动时，IronPDF必须提取其渲染引擎并启动一个Chromium进程，这可能需要30-60秒。较短的超时时间会导致冷启动调用因任务超时错误而失败。温启动调用速度快得多，通常在几秒钟内完成。

是否可以在部署前本地测试Lambda函数？

可以。在开发机器上运行Docker时，使用一个测试事件有效负载运行sam local invoke。SAM会在本地启动容器镜像并调用处理程序函数，使您可以验证PDF生成而无需部署到AWS。

如何减少IronPDF在生产中的冷启动延迟？

使用AWS Lambda Provisioned Concurrency以保持指定数量的实例初始化并准备好处理请求。这消除了这些实例的冷启动，但需支付预留容量的额外费用。

在AWS Lambda上需要哪些IronPDF Maven工件？

您需要ironpdf用于Java API，ironpdf-engine-linux-x64用于本地渲染引擎，以及gRPC传输依赖项grpc-okhttp、grpc-netty-shaded和perfmark-api。ironpdf和ironpdf-engine-linux-x64版本必须匹配。

如何将生成的PDF作为二进制HTTP响应返回？

不要调用pdf.saveAs()，而是使用pdf.getBinaryData()获取原始字节并进行Base64编码。在API网关响应中设置isBase64Encoded: true和Content-Type: application/pdf。对于大文件，将其上传到Amazon S3并返回一个预签名URL是更实用的方法。

Curtis Chau
Curtis Chau
技术作家

Curtis Chau 拥有卡尔顿大学的计算机科学学士学位，专注于前端开发，精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面，喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。

...
阅读更多

准备开始了吗？

版本:2026.6刚刚发布

免费 Maven 下载
立即获取您的免费30 天试用密钥。
无需信用卡或创建账户
Java Maven PDF 库
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

手动安装到您的项目中

Key in blue circle

立即获取免费的 30 天试用版密钥。

Your trial license will be sent to your email address

无任何限制。100% 解锁。无需信用卡。

OR
bullet_checked无需信用卡或创建账户无任何限制。100% 解锁。无需信用卡。
  • Logo Aetna
  • Logo NASA
  • Logo GE
  • Logo Porsche
  • Logo USDA
  • Logo Qatar
Join Millions of Engineers who’ve tried Iron Suite
预约您的免费现场演示
Booking Badge

深受全球数百万工程师信赖

Iron Software 的客户徽标
获取您的无义务咨询
填写下面的表格或通过sales@ironsoftware.com
您的资料将始终保密。
深受全球数百万工程师信赖
Iron Software 的客户徽标
立即获取您的免费30 天试用密钥。
无需信用卡或创建账户
Java Maven PDF 库
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

手动安装到您的项目中