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 Cloud storage에 저장된 SVG 파일을 PNG 이미지로 변환하는 방법을 GroupDocs.Conversion Cloud SDK for Node.JS를 사용하여 보여줍니다.

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로 변환하는 방법

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);

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로 변환하기 위한 모범 사례

Validate SVG Content - 업로드하기 전에 SVG에 외부 스크립트나 악성 페이로드가 포함되어 있지 않은지 확인하십시오. GroupDocs.Conversion은 입력을 정화하지만, 사전 검증을 통해 추가 보안 계층을 제공합니다.
Reuse the Configuration Object - 단일 Configuration 인스턴스를 생성하고 여러 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