Node.JS における SVG から PNG への変換

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

ベクターグラフィックをラスタ画像に変換することは、サーバー上でサムネイル、プレビュー、または PDF を生成する際に頻繁に求められる要件です。 GroupDocs.Conversion Cloud SDK for Node.JS は、クラウド上で完全に SVG から PNG への変換を処理する堅牢なライブラリを提供します。このガイドでは、完全な動作例、対応する cURL ワークフロー、設定のヒント、ベストプラクティスの推奨事項を紹介します。最後まで読むと、任意の Node.JS アプリケーションにサーバーサイドの SVG から PNG への変換を統合できるようになります。

Node.JS における SVG から PNG への変換の完全動作例

この例では、GroupDocs Cloud ストレージに保存されている SVG ファイルを、GroupDocs.Conversion Cloud SDK for Node.JS を使用して 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();
        }
    });

Note: このコード例はコア機能を示しています。プロジェクトで使用する前に、ファイルパス（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 への変換の仕組み

SDK クラスのインポート - 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 や透明な 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);

Download the PNG - 変換後、StorageApi.downloadFile はバイナリデータを取得し、それをローカルファイルシステムに書き込むことができます。

各ステップを理解することで、プロセスをカスタマイズし、エラーを処理し、変換をより大きなワークフローに統合できます。

インストールと構成 GroupDocs.Conversion Cloud SDK for Node.JS

npm install groupdocs-conversion-cloud

SDKはNode.js 12 以降が必要です。インストール後、clientId と clientSecret（GroupDocs Cloud アカウントから取得可能）を使用して構成オブジェクトを作成します。最新のパッケージバージョンについては、download page を参照してください。

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 への変換のベストプラクティス

Validate SVG Content - アップロード前に SVG に外部スクリプトや悪意のあるペイロードが含まれていないことを確認します。GroupDocs.Conversion は入力をサニタイズしますが、事前検証により追加のセキュリティ層が得られます。
Reuse the Configuration Object - Configuration インスタンスを1つ作成し、複数の ConvertApi 呼び出し間で共有してオーバーヘッドを削減します。
Set Reasonable Dimensions - 幅と高さを実際に必要なサイズに制限します。過大な画像は処理時間とメモリ使用量を増加させます。
Stream Large Files - 非常に大きな SVG の場合、全バッファをメモリに読み込むのではなく、ダウンロードをストリーミングすることを検討してください。
Monitor API Usage - 変換クォータを監視し、レートリミットの応答を適切に処理します。

結論

GroupDocs.Conversion Cloud SDK for Node.JS は、サーバー側での SVG から PNG への変換をシンプルかつスケーラブルで安全に行えるようにします。完全なコード例、同等の cURL ワークフロー、上記の構成ヒントに従うことで、あらゆるバックエンドサービスに高性能な画像変換を統合できます。ライセンスオプションを確認してください。実運用では有料サブスクリプションが必要ですが、一時ライセンスページからテスト用の一時ライセンスを取得できます。今日から変換を開始し、ユーザーに自信を持って鮮明な PNG アセットを提供しましょう。

FAQs

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