如何在AWS上設置IronPDF for Java

Q: 為什麼將EphemeralStorage大小設置為1024 MB？

預設的Lambda臨時儲存分配為512 MB。在冷啟動時，IronPDF會將渲染引擎二進位文件和字型快取提取到 /tmp/ 。這些資產可能超過512 MB，導致提取失敗。將EphemeralStorage設置為1024 MB可防止此故障。

Q: 為什麼使用java8.al2基礎圖像而不是java8？

java8 基礎圖像運行在原始的Amazon Linux 1上，其具有過時的包倉庫並缺少IronPDF所需的多個庫。 java8.al2 圖像使用Amazon Linux 2，其中包含當前的軟體包並完全支援Chromium渲染器需要的X11、GTK3和Pango庫。

Q: 我可以在部署之前本地測試Lambda函式嗎？

是的。在開發機上運行Docker，使用測試事件負載運行 sam local invoke 。SAM會在本地啟動容器圖像並調用處理器函式，這樣您就可以在不部署到AWS的情況下驗證PDF生成。

Q: AWS Lambda需要哪些IronPDF Maven工件？

您需要 ironpdf 作為Java API， ironpdf-engine-linux-x64 作為原生渲染引擎，以及gRPC傳輸依賴項 grpc-okhttp 、 grpc-netty-shaded 和 perfmark-api 。 ironpdf 和 ironpdf-engine-linux-x64 版本必須匹配。

Q: 如何將生成的PDF作為二進位HTTP響應返回？

不用調用 pdf.saveAs() ，使用 pdf.getBinaryData() 檢索原始字節並進行Base64編碼。在API Gateway響應中設置 isBase64Encoded: true 和 Content-Type: application/pdf 。對於大型文件，將其上傳到Amazon S3並返回一個預簽名URL是一個更切實可行的方法。

Curtis Chau

Updated: 2026年9月17日

本指南介紹如何使用Docker和AWS SAM在AWS Lambda上部署IronPDF for Java。由於IronPDF依賴於本地Chrome-based渲染引擎，因此無法在標準Zip部署的Lambda功能上運行——Docker是唯一支持的部署模型。以下步驟涵蓋從安裝所需工具、配置pom.xml依賴關係、編寫Lambda處理程式到構建容器映像並使用SAM CLI進行部署的所有內容。

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

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

第一步：

需要哪些先決條件？

在開始之前，請確認開發機器上安裝了以下工具。每個工具在構建和部署管道中發揮特定作用。

IntelliJ IDEA - 本指南中使用的IDE。從jetbrains.com/idea下載。
AWS Toolkit for JetBrains - 在IntelliJ中提供SAM專案精靈和Lambda運行配置。設置說明在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模板並選擇以下選項：

Package Type: Image
Runtime: java8 or java11
SAM Template: Maven

在IntelliJ IDEA中建立AWS Lambda項目並選擇Image包型別

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-aware基礎映像進行構建。 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>

//: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的原因。沒有它，渲染調用將因缺少二進制錯誤而失敗。 gRPC依賴（perfmark-api）是必需的，因為IronPDF通過本地gRPC通道與其渲染引擎通信。 slf4j-simple依賴提供了最小的日誌實現，使得IronPDF的內部日誌可以在CloudWatch中見。

始終對齊ironpdf-engine-linux-x64版本號——混合版本將導致啟動失敗。查看IronPDF for Java在Maven Central上的最新版本字串。

如何編寫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() + "\"}");
        }
    }
}

//: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

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

Text

Timeout設置為400秒。在冷啟動時，IronPDF必須將渲染引擎提取到/tmp並啟動一個本地Chromium進程。這次提取會在第一次調用時花費30–60秒。超過330秒的超時將導致冷啟動調用因任務超時錯誤而失敗。預熱調用要快得多——簡單的HTML到PDF轉換通常在5秒內完成。

MemorySize設置為2048 MB。 Chromium渲染器是記憶體密集型的。AWS Lambda的IronPDF最低可行記憶體為1024 MB，但2048 MB減少了因為複雜頁面導致記憶體不足失敗的風險，同時因為Lambda在記憶體中還按比例縮放CPU分配，產生顯著更快的渲染時間。

EphemeralStorage.Size設置為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"]

//: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後綴表示Amazon Linux 2，IronPDF需要它。舊的java8映像在原始的Amazon Linux 1上運行，使用的是不再接收更新且缺少IronPDF所依賴的幾個包的yum儲存庫。在Java 8上部署IronPDF時，始終使用.al2映像。

yum install塊安裝Chromium需要渲染頁面的X11、GTK3、Pango和字體相關庫。省略其中任何一個包可能產生不完整的PDF輸出或使渲染引擎因缺少共享庫錯誤而崩潰。 libgdiplus包是GDI+相容性所必需的，這在某些IronPDF繪圖操作中使用。

根據實際的包和類名，如果與CMD指令。

如何構建和部署Lambda函式？

配置好Dockerfile、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查看部署的功能，運行測試調用並檢查CloudWatch日誌以查看IronPDF的除錯輸出。

在第一次調用（冷啟動）時，預計響應時間為60–120秒，因為Lambda執行環境啟動並將IronPDF提取到/tmp。在相同的熱實例上的後續調用將在幾秒內返回。如果對於生產工作負載來說冷啟動延遲是一個問題，請考慮使用Lambda Provisioned Concurrency來保持實例熱。

您還可以在部署前本地測試功能，方法是使用測試事件負載運行sam local invoke，前提是Docker正在開發機器上運行。

接下來的步驟是什麼？

Lambda功能現在已部署並渲染PDF。以下指南講解成功部署IronPDF後最常見的下一步：

IronPDF for Java - 入門 - 總覽完整的IronPDF Java API，包括HTML到PDF、URL到PDF和PDF加蓋。
如何在Java中從HTML生成PDF - 將HTML字串、文件和模板渲染為PDF。
如何在Java中將標題和頁尾應用到PDF - 將頁碼、徽標和文字標題新增到Lambda生成的PDF中。
如何在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會在本地啟動容器圖像並調用處理器函式，這樣您就可以在不部署到AWS的情況下驗證PDF生成。

如何在生產中降低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 Gateway響應中設置isBase64Encoded: true和Content-Type: application/pdf。對於大型文件，將其上傳到Amazon S3並返回一個預簽名URL是一個更切實可行的方法。