如何在 Google Cloud 上執行 IronPDF for Java

為什麼預設的 Cloud Function 圖片無法正常運作？

Google Cloud Function 的預設執行環境映像檔在設計上極為精簡——僅包含執行常用語言編寫之函式程式碼所需的套件。 IronPDF 基於 Chromium 的渲染引擎依賴一套更廣泛的 Linux 系統函式庫（字型、圖形函式庫、沙箱工具），而這些函式庫在標準映像檔中並未包含。

Google 在 Google Cloud Functions 系統套件參考文件中，針對每個執行環境發布了完整的可用系統套件清單。 Chromium 的依賴項未包含在任何標準的第二代執行環境中。 嘗試在預設圖片中載入 IronPDF 引擎，將導致啟動時發生原生函式庫載入失敗。

解決方案是建立一個自訂 Docker 映像檔，在加入函式二進位檔之前，先明確安裝這些套件。 此方法獲得 Google Cloud Functions 的全面支援，也是針對任何需要原生二進位檔的函式所建議的策略。 請參閱 IronPDF Linux 部署指南，以獲取應包含的完整套件清單。

如何為 Google Cloud 建立自訂 Dockerfile？

自訂的 Dockerfile 可讓您完全掌控執行環境。 請從官方的 Google Cloud Functions Java 基礎映像開始，然後安裝 Chromium 所需的系統函式庫。

以下 Dockerfile 範例展示了建議的編寫模式。 請將 COPY 和 CMD 中的內容替換為您功能專案的具體資訊：

//:path=Dockerfile
# Use the official Google Cloud Functions Java 17 base image
FROM gcr.io/google-appengine/java17:latest

# Install Chrome system dependencies required by IronPDF's rendering engine
RUN apt-get update && apt-get install -y \
    libglib2.0-0 \
    libnss3 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libcups2 \
    libdrm2 \
    libxkbcommon0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxrandr2 \
    libgbm1 \
    libasound2 \
    libpango-1.0-0 \
    libpangocairo-1.0-0 \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

# Grant execute permissions on /tmp so the IronPDF engine can extract there
RUN chmod 777 /tmp/

# Copy the compiled JAR and set the entry point
COPY target/your-function.jar /app/function.jar
CMD ["java", "-jar", "/app/function.jar"]

chmod 777 /tmp/ 這一行是必要的，因為 IronPDF 需要在初始化時寫入並執行引擎二進位檔。 若工作目錄缺乏執行權限，引擎將無法啟動。

如何為 Google Cloud 部署設定 pom.xml？

標準的 ironpdf Maven 工件包含適用於多種平台的引擎二進位檔。 針對 Google Cloud Functions（運行於 Linux x86-64 環境），請新增平台專屬的引擎組件，以保持部署映像的輕量化，並確保始終能取得正確的二進位檔：

//:path=pom.xml
<dependencies>

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

//:path=pom.xml
<dependencies>

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

請務必將版本號更新為最新發佈的 IronPDF for Java 版本。 ironpdf-engine-linux-x64 組件的版本必須與核心 ironpdf 組件的版本完全一致。

如何新增 Maven Shade 外掛程式？

當以 uber-JAR（fat JAR）形式部署至 Google Cloud Functions 時，maven-shade-plugin 可確保所有傳遞性依賴項的服務載入檔能正確合併。 若未如此處理，某些 gRPC 服務註冊可能會被靜默捨棄，導致引擎無法初始化。

請將以下外掛程式設定新增至您的 pom.xml 檔案中的 <build><plugins> 區段：

//:path=pom.xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>

            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

//:path=pom.xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>

            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

ServicesResourceTransformer 是關鍵部分。 它會將每個依賴 JAR 檔中的 META-INF/services/ 條目合併為單一檔案。由於 gRPC 使用 Java 的 ServiceLoader 機制，因此必須在執行時提供合併後的服務檔案，才能讓傳輸選取機制（HTTP/2 與純文字）正常運作。

如何新增可選的 gRPC 依賴項？

在某些部署配置中——特別是當使用帶有特定版本 Google Cloud Functions 框架的陰影 JAR 時——需要明確的 gRPC 傳輸依賴項。 若函式因 gRPC 傳輸或通道錯誤而無法啟動，請加入以下內容：

//:path=pom.xml
<dependencies>

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

//:path=pom.xml
<dependencies>

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

在大多數情況下，在生產環境中包含 grpc-netty-shaded 即可。 grpc-okhttp 傳輸方式是一種更輕量級的替代方案，當縮小圖片大小是首要考量時特別適用。 僅當遇到關於缺少追蹤註解的類路徑警告時，才添加 perfmark-api。

如何為 Google Cloud Functions 設定資源限制？

IronPDF 在首次被呼叫時，會在 Cloud Function 容器內啟動一個 Chromium 子程序。 Chromium 的啟動與初始渲染過程會消耗大量記憶體，且該函式必須維持足夠長的時間，以供引擎完成初始化。Cloud Functions 的預設資源限制過低，無法確保運作的可靠性。

在 Google Cloud Console 或透過 gcloud CLI 部署函式時，請設定以下限制：

以上內容僅供參考。 若需處理大量或複雜的 PDF 生成任務，可能需要分配較多的記憶體。 請在 Google Cloud Console 中監控 Cloud Functions 的記憶體使用指標，若發現記憶體不足錯誤，請提高限制值。

如何設定工作目錄和檔案權限？

IronPDF 引擎會在啟動時將其二進位檔解壓縮至工作目錄。在 Google Cloud Functions 上，唯一可寫入且可執行的路徑是 /tmp/。 在呼叫任何 IronPDF API 之前，請明確設定工作目錄，並確保 Dockerfile 已為該路徑授予必要的權限。

請在函式入口點的頂端，於任何 PDF 操作之前加入此設定呼叫：

//:path=/static-assets/pdf/content-code-examples/tutorials/google-cloud/configure-working-directory.java
import com.ironsoftware.ironpdf.設定s;
import java.nio.file.Paths;

public class PdfFunction {
    static {
        // Must be called before any IronPDF operation.
        // /tmp/ is the only writable and executable directory in Cloud Functions.
        設定s.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));
    }
}

//:path=/static-assets/pdf/content-code-examples/tutorials/google-cloud/configure-working-directory.java
import com.ironsoftware.ironpdf.設定s;
import java.nio.file.Paths;

public class PdfFunction {
    static {
        // Must be called before any IronPDF operation.
        // /tmp/ is the only writable and executable directory in Cloud Functions.
        設定s.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));
    }
}

接著將對應的權限指令加入您的 Dockerfile 中：

//:path=Dockerfile
# Ensure the IronPDF engine can extract and run binaries from /tmp/
RUN chmod 777 /tmp/

使用 static {} 初始化區塊，可確保在函式中的任何類別嘗試載入 IronPDF 引擎之前，工作目錄已設定完成。若在實例方法或請求處理常式中設定此區塊，則存在其他執行緒在路徑設定完成前即初始化引擎的風險。

接下來該怎麼做？

本指南涵蓋了使用自訂 Docker 容器在 Google Cloud Function 中執行 IronPDF for Java 的完整設定流程。 重點如下：使用自訂的 Dockerfile 來安裝 Chrome 系統依賴項，包含 ironpdf-engine-linux-x64 Maven 工件，將工作目錄設定為 /tmp/，將超時設定為至少 330 秒且記憶體至少 2,048 MB，並加入 maven-shade-plugin 以合併服務載入檔。

若要進一步了解 IronPDF for Java 的功能，請參閱 IronPDF for Java 文件，或試試以下指南：

• Linux 版 IronPDF for Java — 了解 Linux 部署所需的完整 Chrome 依賴項清單
• AWS Lambda 上的 IronPDF for Java — 類似的基於 Docker 的 AWS 部署指南
• Java 中的 HTML 轉 PDF — 功能邏輯的核心渲染工作流程

立即取得免費試用授權，在您的 Google Cloud 環境中測試 IronPDF for Java。 正式部署需使用授權金鑰。 當您準備好正式上線時，請購買授權。