已更新:2026年5月3日

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

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

今天在您的项目中使用 IronPDF，免费试用。

第一步：

需求条件是什么？ {#prerequisites}

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

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之前进行本地调用测试，也请安装：

Java 8 JDK — 从Oracle JDK 8下载页面获取。
Apache Maven — 请遵循Maven安装指南。

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

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

在 IntelliJ IDEA 中创建 AWS Lambda 项目，并选择了 Image 包类型

显示 Java 8 运行时和 Maven SAM 模板的 AWS Lambda 配置界面

为什么必须使用Docker而不是Zip部署？ {#why-docker}

AWS Lambda支持两种部署包类型：Zip存档和容器镜像。 Zip部署非常适合轻量级的Java函数，因为运行时环境完全由AWS管理。然而，IronPDF 随附了一个原生二进制文件（基于 Chrome 的 PDF 渲染引擎），该文件必须在运行时进行解压并执行。针对 ZIP 部署的 Lambda 执行环境将文件系统写入操作限制在 /tmp 范围内，且 ZIP 包层的限制导致无法解压大型原生二进制文件。

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

实际操作很简单：在 template.yaml 中设置 PackageType: Image，并使用支持 Docker 的基础镜像进行构建。 SAM CLI将处理剩下的部分。

如何配置Maven依赖？ {#Maven-dependencies}

pom.xml 文件除标准 Lambda SDK 之外，还需要三类额外依赖项：IronPDF Java 库、IronPDF Linux x64 渲染引擎，以及 IronPDF 引擎内部使用的 gRPC 传输协议。

打开 pom.xml，并在 <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>

//: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 构建包包含针对 64 位 Linux 系统预编译的基于 Chromium 的渲染引擎。这就是允许IronPDF在Lambda容器内将HTML渲染为PDF的原因。没有它，渲染调用将因为缺少二进制文件而失败。由于 IronPDF 通过本地 gRPC 通道与其渲染引擎进行通信，因此需要 gRPC 依赖项（grpc-okhttp, grpc-netty-shaded, perfmark-api）。 slf4j-simple 依赖项提供了一个最简日志记录实现，以便在 CloudWatch 中查看 IronPDF 的内部日志。

请务必保持 ironpdf 和 ironpdf-engine-linux-x64 版本号的一致性——版本混用将导致启动失败。查看Maven Central上的IronPDF for Java以获取最新版本的字符串。

如何编写Lambda处理程序？ {#lambda-handler}

Lambda 处理程序类接收 APIGatewayProxyRequestEvent，生成 PDF 文件，并返回 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() + "\"}");
        }
    }
}

//: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 指向该目录。如果省略此设置，引擎将无法启动，每次渲染调用都会抛出异常。

pdf.saveAs("/tmp/output.pdf") 调用将渲染后的文件存储在临时 /tmp 文件系统中。如果 Lambda 函数需要将 PDF 作为二进制响应返回或上传至 S3，请使用 pdf.getBinaryData() 获取字节流，而非写入磁盘。对于大型工作负载，上传到Amazon S3并返回预签名URL是推荐的模式。

如何配置SAM模板？ {#sam-template}

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

请按以下方式更新 Globals 部分中的 template.yaml：

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

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

YAML

超时时间设置为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}

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"]

两个阶段的基础图像均使用 java8.al2 标签，而非普通的 java8。后缀 .al2 表示 Amazon Linux 2，这是 IronPDF 的必备系统。旧版 java8 镜像运行在原始的 Amazon Linux 1 上，该系统使用 yum 仓库，这些仓库已不再接收更新，且缺少 IronPDF 依赖的若干软件包。在 Java 8 上部署 IronPDF 时，请务必使用 .al2 图像。

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

如果您的实际包名和类名与 helloworld.App 不同，请更新 CMD 指令以匹配您的实际名称。

如何构建和部署Lambda函数？ {#build-deploy}

在完成 Dockerfile、pom.xml 和 App.java 的配置后，请在项目根目录下运行以下两条 SAM CLI 命令。

步骤1—构建容器镜像：

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

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

SHELL

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

步骤2—部署到AWS：

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

//: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日志。

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

在部署前，您还可以通过在开发机上运行 Docker 并使用测试事件负载执行 sam local invoke 来本地测试该功能。

下一步是什么？ {#next-steps}

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

IronPDF for Java — 入门指南 — 总览完整的IronPDF Java API，其中包括HTML到PDF、URL到PDF和PDF印记。
如何在Java中将HTML生成PDF — 将HTML字符串、文件和模板渲染为PDF。
如何在Java中对PDF应用页眉和页脚 — 为Lambda生成的PDF添加页码、logo和文本页眉。
如何在Java中向PDF添加水印 — 在返回给调用者前为PDF输出加盖文本或图像水印。
IronPDF许可 — 生产Lambda部署的许可选项，包括部署数量许可。

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

除了开发之外，Curtis 对物联网 (IoT) 有浓厚的兴趣，探索将硬件和软件集成的新方法。在空闲时间，他喜欢玩游戏和构建 Discord 机器人，将他对技术的热爱与创造力相结合。

准备开始了吗？

版本: 2026.5 just released

查看许可证

还在滚动吗？

想快速获得证据？
运行示例看着你的HTML代码变成PDF文件。

查看许可证

客户亮点：

开发者焦点：

网络研讨会：

开始免费 30 天试用

本页内容

目录

需求条件是什么？ {#prerequisites}

为什么必须使用Docker而不是Zip部署？ {#why-docker}

如何配置Maven依赖？ {#Maven-dependencies}

如何编写Lambda处理程序？ {#lambda-handler}

如何配置SAM模板？ {#sam-template}

如何构建Dockerfile？{#dockerfile}

如何构建和部署Lambda函数？ {#build-deploy}

下一步是什么？ {#next-steps}

常见问题解答

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

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

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

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

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

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

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

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

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

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

还在滚动吗？

钢铁支援团队

开始免费 30 天试用

本页内容

目录

需求条件是什么？ {#prerequisites}

为什么必须使用Docker而不是Zip部署？ {#why-docker}

如何配置Maven依赖？ {#Maven-dependencies}

如何编写Lambda处理程序？ {#lambda-handler}

如何配置SAM模板？ {#sam-template}

如何构建Dockerfile？{#dockerfile}

如何构建和部署Lambda函数？ {#build-deploy}

下一步是什么？ {#next-steps}

常见问题解答

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

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

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

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

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

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

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

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

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

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

还在滚动吗？

下一步：开始免费 30 天试用

Thank You

下一步：开始免费 30 天试用

Want to deploy IronSuite to a live project for FREE?

What’s included?

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

钢铁支援团队