1. IronPDF
  2. 開始使用
  3. 建立 編輯 PDF Java AWS Lambda

Curtis Chau
Curtis Chau
更新:

本指南將逐步說明如何使用 Docker 和 AWS SAM，在 AWS Lambda 上部署 IronPDF for Java。 由於 IronPDF 依賴原生的 Chrome 渲染引擎，因此無法在標準的 ZIP 部署 Lambda 函式上運行 — Docker 是唯一受支援的部署模式。 以下步驟涵蓋了從安裝所需工具、設定 pom.xml 依賴項、編寫 Lambda 處理程序，到構建容器映像並使用 SAM CLI 進行部署的完整流程。

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

立即透過免費試用，在您的專案中開始使用 IronPDF。

第一步：
green arrow pointer

目錄

有哪些先決條件？ {#prerequisites}

開始之前，請確認開發機器上已安裝以下工具。每個工具在建置與部署流程中都扮演著特定的角色。

  • 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 Community Edition。

若要在部署至 AWS 之前進行本地調用測試，請同時安裝：

當所有工具就緒後，請開啟 IntelliJ IDEA，並透過"檔案"→"新增"→"專案"建立一個新專案。 在專案精靈中，選取 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 依賴項提供了一種最簡化的記錄實作，使 IronPDF 的內部記錄能在 CloudWatch 中顯示。

請務必保持 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.Co/ntext;
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.Co/ntext;
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。

請將 template.yaml 中的 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
YAML

超時設定為 400 秒。 在冷啟動時，IronPDF 必須將渲染引擎提取至 /tmp 並啟動一個本地的 Chromium 進程。 首次執行此提取操作可能需要 30 至 60 秒。 若超時設定值低於 330 秒，將導致冷啟動呼叫失敗，並產生任務超時錯誤。 預熱後的調用速度快得多——簡單的 HTML 轉 PDF/A 轉換通常在 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}

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 控制台，以檢視已部署的功能、執行測試呼叫，並檢查 CloudWatch 日誌中的 IronPDF 除錯輸出。

首次呼叫（冷啟動）時，由於 Lambda 執行環境啟動以及 IronPDF 將其渲染引擎提取至 /tmp，預計回應時間為 60 至 120 秒。 後續對同一暖機實例的呼叫將在數秒內返回結果。 若生產環境工作負載的冷啟動延遲是您的顧慮，請考慮使用 Lambda 預配置並發功能來維持執行個體的暖機狀態。

若開發機台已運行 Docker，您亦可透過執行 sam local invoke 並傳入測試事件載荷，在部署前於本地端測試該功能。

接下來該怎麼做？ {#next-steps}

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 將在本地啟動容器映像並調用處理函數，讓您無需部署至 AWS 即可驗證 PDF 生成效果。

如何降低 IronPDF 在生產環境中的冷啟動延遲？

使用 AWS Lambda 預配置並發功能，可讓指定數量的執行個體保持初始化狀態並隨時準備處理請求。此功能可消除這些執行個體的冷啟動問題，但需支付預留容量的額外費用。

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 是一種更實用的做法。

Curtis Chau
Curtis Chau
  立即與工程團隊聯繫
技術撰稿人

Curtis Chau 擁有卡爾頓大學（Carleton University）的電腦科學學士學位，專精於前端開發，並精通 Node.js、TypeScript、JavaScript 及 React。他熱衷於打造直觀且美觀的用戶介面，喜歡運用現代框架，並創建結構完善、視覺上吸引人的手冊。

除了開發工作之外，Curtis 對物聯網（IoT）抱有濃厚興趣，致力於探索整合硬體與軟體的創新方法。閒暇時，他喜歡玩遊戲和開發 Discord 機器人，將對科技的熱愛與創意相結合。

準備開始了嗎？
版本： 2026.5 just released
Still Scrolling Icon

還在捲動嗎？

想要快速證明？
執行範例 觀看您的 HTML 變成 PDF。