Node.JS 中的 SVG 轉 PNG 轉換

Mon, 17 Aug 2026 08:29:07 +0000

將向量圖形轉換為點陣圖像是生成縮圖、預覽或伺服器端 PDF 時的常見需求。 GroupDocs.Conversion Cloud SDK for Node.JS 提供了一個強大的庫，能在雲端完整處理 SVG 到 PNG 的轉換。在本指南中，您將看到完整的工作範例、相應的 cURL 工作流程、配置技巧以及最佳實踐建議。完成後，您將能將伺服器端的 SVG 轉 PNG 轉換整合到任何 Node.JS 應用程式中。

Node.JS 中 SVG 轉 PNG 完整工作範例

此範例示範如何使用 GroupDocs.Conversion Cloud SDK for Node.JS，將儲存在 GroupDocs Cloud 儲存空間中的 SVG 檔案轉換為 PNG 圖像。

const { Configuration, ConvertApi, ConvertDocumentRequest, ConvertSettings, PngOptions, StorageApi, DownloadFileRequest } = require("@groupdocs/conversion-cloud");
const fs = require('fs');
const path = require('path');

// -----------------------------------------------------------------------------
// Configuration – replace with your own credentials
// -----------------------------------------------------------------------------
const config = new Configuration({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET"
});

const convertApi = new ConvertApi(config);
const storageApi = new StorageApi(config);

// -----------------------------------------------------------------------------
// Define source SVG and target PNG locations inside GroupDocs Cloud storage
// -----------------------------------------------------------------------------
const inputSvgPath = "input/sample.svg";          // SVG stored in cloud storage
const outputPngPath = "output/sample.png";       // Desired PNG location

// -----------------------------------------------------------------------------
// PNG conversion options – set dimensions to control memory/CPU usage
// -----------------------------------------------------------------------------
const pngOptions = new PngOptions({
    width: 1024,               // Resize width (optional)
    height: 768,               // Resize height (optional)
    backgroundColor: "#FFFFFF" // Ensure opaque background
});

// -----------------------------------------------------------------------------
// Build conversion settings object
// -----------------------------------------------------------------------------
const convertSettings = new ConvertSettings({
    filePath: inputSvgPath,
    format: "png",
    outputPath: outputPngPath,
    options: pngOptions
});

const convertRequest = new ConvertDocumentRequest(convertSettings);

// -----------------------------------------------------------------------------
// Execute conversion, then download the PNG locally
// -----------------------------------------------------------------------------
convertApi.convertDocument(convertRequest)
    .then(convResult => {
        console.log("Conversion succeeded. Cloud file:", convResult.path);
        const downloadReq = new DownloadFileRequest({ path: convResult.path });
        return storageApi.downloadFile(downloadReq);
    })
    .then(fileBuffer => {
        const localFile = path.resolve(__dirname, "sample.png");
        fs.writeFileSync(localFile, fileBuffer);
        console.log("PNG downloaded to:", localFile);
    })
    .catch(err => {
        console.error("Error during SVG → PNG conversion:", err);
    })
    .finally(() => {
        // Clean up HTTP client resources if the SDK exposes a close method
        if (config && config.httpClient && typeof config.httpClient.close === "function") {
            config.httpClient.close();
        }
    });

注意： 此程式碼範例展示了核心功能。在將其用於您的專案之前，請確保更新檔案路徑（input/sample.svg、output/sample.png 等）以符合實際檔案位置，驗證所有必要的相依項已正確安裝，並在開發環境中徹底測試。如果您遇到任何問題，請參閱官方文件或聯繫支援團隊以獲得協助。

使用 cURL 的 REST API 進行 SVG 到 PNG 的轉換

如果您偏好純粹的 REST 方法，亦可使用 cURL 命令執行相同的轉換。以下步驟說明如何取得存取權杖、上傳 SVG、啟動轉換以及下載 PNG。

驗證並取得存取令牌

curl -X POST "https://api.groupdocs.cloud/v2.0/auth/token" \
     -H "Content-Type: application/json" \
     -d '{
           "client_id": "YOUR_CLIENT_ID",
           "client_secret": "YOUR_CLIENT_SECRET"
         }'

回應中包含一個 access_token，您將在後續呼叫中使用它。

上傳來源 SVG 檔案

curl -X POST "https://api.groupdocs.cloud/v2.0/storage/upload?path=input/sample.svg" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@/path/to/local/sample.svg"

執行 SVG 到 PNG 的轉換

curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "filePath": "input/sample.svg",
           "format": "png",
           "outputPath": "output/sample.png",
           "options": {
               "width": 1024,
               "height": 768,
               "backgroundColor": "#FFFFFF"
           }
         }'

API 會返回雲端儲存中新建立的 PNG 檔案的路徑。

下載產生的 PNG 檔案

curl -X GET "https://api.groupdocs.cloud/v2.0/storage/download?path=output/sample.png" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o sample.png

這些 cURL 命令讓您在不編寫任何程式碼的情況下，完全掌控轉換過程。如需更多詳細資訊，請參閱官方 API 文件。

如何在 Node.JS 中將 SVG 轉換為 PNG 工作原理

Import SDK Classes - require("@groupdocs/conversion-cloud") 陳述式會載入必要的類別，例如 ConvertApi、ConvertSettings 和 PngOptions（API 參考）。

const { ConvertApi, ConvertSettings, PngOptions } = require("@groupdocs/conversion-cloud");

設定驗證 - Configuration 物件保存您的 clientId 和 clientSecret。此物件會傳遞給 ConvertApi 和 StorageApi，以授權所有後續呼叫。

const config = new Configuration({ clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET" });

定義輸入和輸出路徑 - inputSvgPath 指向雲端存儲中的 SVG，而 outputPngPath 指定 PNG 應保存的位置。

const inputSvgPath = "input/sample.svg";
const outputPngPath = "output/sample.png";

設定 PNG 選項 - PngOptions 讓您能控制尺寸和背景顏色，對於大型或透明的 SVG 非常有用。

const pngOptions = new PngOptions({ width: 1024, height: 768, backgroundColor: "#FFFFFF" });

建立轉換設定並執行 - ConvertSettings 將檔案路徑、目標格式、輸出位置和選項打包。convertDocument 方法執行轉換，結果包含 PNG 的雲端路徑。

const convertSettings = new ConvertSettings({ filePath: inputSvgPath, format: "png", outputPath: outputPngPath, options: pngOptions });
const convertRequest = new ConvertDocumentRequest(convertSettings);
convertApi.convertDocument(convertRequest);

下載 PNG - 轉換後，StorageApi.downloadFile 會檢索二進位資料，您可以將其寫入本機檔案系統。

了解每個步驟有助於您自訂流程、處理錯誤，並將轉換整合到更大的工作流程中。

安裝與設定 GroupDocs.Conversion Cloud SDK for Node.JS

npm install groupdocs-conversion-cloud

SDK 需要 Node.js 12 或更高版本。安裝完成後，建立一個包含您的 clientId 和 clientSecret（可從您的 GroupDocs Cloud 帳戶獲取）的配置物件。請參閱下載頁面以取得最新的套件版本。

const { Configuration } = require("@groupdocs/conversion-cloud");
const config = new Configuration({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET"
});

確保憑證具有訪問存儲和轉換服務的權限。配置完成後，您可以如代碼示例所示實例化 ConvertApi 和 StorageApi。

微調 PNG 轉換設定

PngOptions 類別提供了多個可調整的屬性：

width / height - 定義輸出解析度。較大的值會提升品質，但會佔用更多記憶體。
```
const pngOptions = new PngOptions({ width: 1920, height: 1080 });
```

backgroundColor - 為包含透明度的 SVG 設定實心背景。

const pngOptions = new PngOptions({ backgroundColor: "#000000" });

compressionLevel - （如果支援）選擇 0（無壓縮）至 9（最高壓縮）之間的壓縮等級，以減少檔案大小。
```
const pngOptions = new PngOptions({ compressionLevel: 6 });
```

這些選項是透過 ConvertSettings 的 options 屬性傳遞的。請參閱 API 參考以獲取可用設定的完整列表。

有效的 SVG 轉 PNG 轉換最佳實踐

驗證 SVG 內容 - 確保 SVG 在上傳前不包含外部腳本或惡意負載。 GroupDocs.Conversion 會對輸入進行清理，但預先驗證可提供額外的安全層。
重用 Configuration 物件 - 建立單一個 Configuration 實例，並在多個 ConvertApi 呼叫間共享，以減少開銷。
設定合理的尺寸 - 將寬度和高度限制在實際需要的尺寸。過大的圖像會增加處理時間和記憶體使用。
串流大型檔案 - 對於非常大的 SVG，建議使用串流下載，而不是將整個緩衝區載入記憶體。
監控 API 使用情況 - 留意您的轉換配額，並優雅地處理速率限制回應。

結論

GroupDocs.Conversion Cloud SDK for Node.JS 使伺服器端的 SVG 到 PNG 轉換變得直接、可擴展且安全。通過遵循完整的程式碼範例、等效的 cURL 工作流程以及上述配置提示，您可以將高效能影像轉換整合到任何後端服務中。請記得檢視授權選項，生產部署需要付費訂閱，您也可以從臨時授權頁面取得用於測試的臨時授權。立即開始轉換，為您的使用者自信地交付清晰的 PNG 資產。

常見問題

如何在 Node.JS 中使用 GroupDocs 執行 SVG 轉 PNG 轉換？
使用 GroupDocs.Conversion Cloud SDK for Node.JS。將 SVG 上傳到雲端存儲，配置 PngOptions，調用 convertDocument，然後下載 PNG。本文中的完整代碼示例展示了每個步驟。

我可以一次批量轉換多個 SVG 檔案嗎？
是的。遍歷 SVG 路徑清單，對每個檔案呼叫相同的轉換請求。SDK 會獨立處理每個請求，讓您能將所有 PNG 結果存儲在同一個輸出資料夾中。

如果轉換失敗並出現錯誤，我該怎麼辦？
檢查 catch 區塊中返回的錯誤訊息。常見問題包括憑證無效、檔案路徑遺失或不支援的 SVG 功能。請參閱官方文件以獲取詳細的錯誤代碼和故障排除步驟。

我可以在哪裡找到有關 PNG 選項的更多資訊？
所有可配置的屬性都列在 PngOptions 的 API 參考中。請訪問 API 參考以探索其他設定，例如壓縮等級和色彩深度。

svg processing on Document Processing REST APIs | GroupDocs Cloud