Node.JS에서 PDF를 DOCX로 변환

Mon, 03 Aug 2026 10:51:03 +0000

PDF 파일을 DOCX 형식으로 변환하는 것은 문서 중심 애플리케이션을 구축할 때 자주 요구되는 작업이며, 특히 편집 가능한 Word 출력이 필요할 때 그렇습니다. GroupDocs.Conversion Cloud SDK for Node.js는 이 작업을 간단하고 확장 가능하게 만드는 강력한 API를 제공합니다. 이 가이드에서는 전체 비동기 코드 샘플을 확인하고, cURL REST 호출로 동일한 결과를 얻는 방법을 배우며, SDK를 설정하고 신뢰할 수 있는 변환을 위한 모범 사례 권장 사항을 적용하는 방법을 다룹니다.

전체 코드 예제: Node.JS에서 비동기 PDF를 DOCX로 변환

이 예제에서는 GroupDocs.Conversion Cloud SDK for Node.js를 사용하여 비동기 PDF에서 DOCX로 변환하는 방법을 보여줍니다.

// PDF to DOCX conversion using GroupDocs.Conversion Cloud SDK for Node.js

const GroupDocsConversionCloud = require('groupdocs-conversion-cloud');
const path = require('path');

// -------------------- Configuration --------------------
const CLIENT_ID = process.env.GROUPDOCS_CLIENT_ID || 'YOUR_CLIENT_ID';
const CLIENT_SECRET = process.env.GROUPDOCS_CLIENT_SECRET || 'YOUR_CLIENT_SECRET';

// Initialize API client
const apiInstance = new GroupDocsConversionCloud.ConversionApi();
apiInstance.apiClient = new GroupDocsConversionCloud.ApiClient();
apiInstance.apiClient.basePath = 'https://api.groupdocs.cloud';
apiInstance.apiClient.authentications['JWT'].clientId = CLIENT_ID;
apiInstance.apiClient.authentications['JWT'].clientSecret = CLIENT_SECRET;

// -------------------- Conversion Logic --------------------
async function convertPdfToDocx() {
    try {
        // Input file information (must already be uploaded to GroupDocs Cloud storage)
        const inputFileInfo = new GroupDocsConversionCloud.FileInfo();
        inputFileInfo.filePath = path.normalize('input.pdf'); // generic path in cloud storage

// DOCX specific conversion options (optional, shown for demonstration)
        const docxOptions = new GroupDocsConversionCloud.DocxConvertOptions();
        docxOptions.preserveOriginalFormatting = true; // keep original PDF layout as much as possible
        docxOptions.password = null; // if PDF is password protected, set it here

// Build conversion request
        const convertRequest = new GroupDocsConversionCloud.ConvertDocumentRequest();
        convertRequest.format = 'docx';
        convertRequest.fileInfo = inputFileInfo;
        convertRequest.outputPath = path.normalize('output.docx'); // result will be stored in cloud storage
        convertRequest.options = docxOptions; // attach format‑specific options

// Perform conversion (async)
        const conversionResult = await apiInstance.convertDocument(convertRequest);

// conversionResult contains the path of the generated file and other metadata
        console.log('Conversion succeeded.');
        console.log('Output file path:', conversionResult.path);
        console.log('File size (bytes):', conversionResult.size);
    } catch (error) {
        // Detailed error handling
        if (error.response && error.response.body) {
            console.error('API error:', error.response.body);
        } else {
            console.error('Unexpected error:', error.message);
        }
    }
}

// -------------------- Execution --------------------
(async () => {
    // Optional: set a timeout to avoid hanging indefinitely
    const timeoutMs = 300000; // 5 minutes
    const timeout = setTimeout(() => {
        console.error('Conversion timed out after', timeoutMs / 1000, 'seconds');
        process.exit(1);
    }, timeoutMs);

await convertPdfToDocx();

clearTimeout(timeout);
    // Graceful shutdown
    process.exit(0);
})();

Note: 이 코드 예제는 핵심 기능을 보여줍니다. 프로젝트에서 사용하기 전에 파일 경로(input.pdf, output.docx 등)를 실제 위치에 맞게 업데이트하고, 모든 필수 종속성이 설치되었는지 확인한 다음 개발 환경에서 충분히 테스트하십시오. 문제가 발생하면 공식 문서를 참조하거나 지원 팀에게 문의하십시오.

cURL 및 REST API를 사용하여 문서 변환

코드를 작성하지 않고도 GroupDocs.Conversion Cloud REST 엔드포인트를 직접 호출하여 동일한 PDF를 DOCX로 변환할 수 있습니다. 아래 단계에서는 액세스 토큰을 얻고, PDF를 업로드하고, 변환을 시작하고, 결과 DOCX 파일을 다운로드하는 방법을 보여줍니다.

인증하고 액세스 토큰을 가져옵니다
YOUR_CLIENT_ID와 YOUR_CLIENT_SECRET를 귀하의 자격 증명으로 교체하십시오.

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

응답에는 이후 호출에서 사용할 access_token이 포함되어 있습니다.

소스 PDF 업로드

curl -X PUT "https://api.groupdocs.cloud/v1.0/storage/file/input.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/pdf" \
     --data-binary @./local/input.pdf

변환 실행

curl -X POST "https://api.groupdocs.cloud/v1.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "format":"docx",
           "fileInfo":{"filePath":"input.pdf"},
           "outputPath":"output.docx",
           "options":{"preserveOriginalFormatting":true}
         }'

응답은 생성된 DOCX 파일의 경로를 반환합니다.

변환된 DOCX 다운로드

curl -X GET "https://api.groupdocs.cloud/v1.0/storage/file/output.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o ./local/output.docx

요청 페이로드 및 추가 옵션에 대한 자세한 내용은 공식 API 문서를 참조하세요.

Node.JS에서 PDF를 DOCX로 변환하기 자세히 살펴보기

아래는 비동기 코드 샘플의 핵심 부분에 대한 간결한 안내입니다.

클라이언트 가져오기 및 구성

const GroupDocsConversionCloud = require('groupdocs-conversion-cloud');
const apiInstance = new GroupDocsConversionCloud.ConversionApi();

ConversionApi 클래스 (API reference)는 모든 변환 작업의 진입점입니다.

인증 자격 증명 설정

apiInstance.apiClient.authentications['JWT'].clientId = CLIENT_ID;
apiInstance.apiClient.authentications['JWT'].clientSecret = CLIENT_SECRET;

JWT 인증은 클라우드 서비스에 대한 각 요청을 보호합니다.

입력 파일 정보를 준비합니다

const inputFileInfo = new GroupDocsConversionCloud.FileInfo();
inputFileInfo.filePath = path.normalize('input.pdf');

FileInfo는 API에 소스 PDF가 GroupDocs Cloud 스토리지에 어디에 있는지 알려줍니다.

DOCX‑특정 옵션 구성

const docxOptions = new GroupDocsConversionCloud.DocxConvertOptions();
docxOptions.preserveOriginalFormatting = true;

DocxConvertOptions를 사용하면 원래 레이아웃을 유지하고 필요에 따라 비밀번호를 처리할 수 있습니다.

변환 요청 생성 및 전송

const convertRequest = new GroupDocsConversionCloud.ConvertDocumentRequest();
convertRequest.format = 'docx';
convertRequest.fileInfo = inputFileInfo;
convertRequest.outputPath = path.normalize('output.docx');
convertRequest.options = docxOptions;
const conversionResult = await apiInstance.convertDocument(convertRequest);

convertDocument 메서드는 실제 변환을 수행하고 출력 경로 및 파일 크기와 같은 메타데이터를 반환합니다.

설치 및 구성 GroupDocs.Conversion Cloud SDK for Node.JS

패키지 설치

npm install groupdocs-conversion-cloud

패키지는 공개 npm 레지스트리에서 사용할 수 있습니다. 버전 세부 정보를 보려면 다운로드 페이지를 확인하세요.

필수 조건
- Node.js 12 이상.
- 클라이언트 ID와 클라이언트 비밀키가 있는 GroupDocs Cloud 계정.
프로젝트에서 SDK 초기화 (전체 예제에서 발췌)

const GroupDocsConversionCloud = require('groupdocs-conversion-cloud');
const apiInstance = new GroupDocsConversionCloud.ConversionApi();
apiInstance.apiClient.basePath = 'https://api.groupdocs.cloud';

지역 엔드포인트를 사용하는 경우 basePath를 조정하십시오.

고성능 문서 변환을 위한 모범 사례

API 클라이언트를 재사용하여 각 변환마다 새 인스턴스를 만들지 마세요. 이렇게 하면 인증 오버헤드가 줄어듭니다.
스트리밍 업로드 활성화를 사용하여 큰 PDF를 메모리에 전체 로드하지 않도록 합니다.
합리적인 제한 시간 설정(예: 5 분)으로 작업이 중단되는 것을 방지하면서 복잡한 문서도 완료될 수 있게 합니다.
필요할 때만 원본 서식 유지; 비활성화하면 텍스트 전용 PDF의 변환 속도를 높일 수 있습니다.
API 사용 제한 모니터링을 GroupDocs 계정 대시보드에서 확인하여 배치 작업 중 제한에 걸리지 않도록 합니다.

결론

GroupDocs.Conversion Cloud SDK for Node.js 은 PDF를 DOCX로 변환하는 작업을 간편하게 해줍니다. 전체 기능을 갖춘 라이브러리를 사용하든 cURL을 이용한 직접 REST 호출을 하든 상관없습니다. 비동기 코드 샘플을 따라하고, 클라이언트를 올바르게 구성하며, 위의 성능 팁을 적용하면 어떤 Node.JS 서비스에도 신뢰할 수 있는 문서 변환을 통합할 수 있습니다. 프로덕션 사용을 위해 적절한 라이선스를 획득하는 것을 기억하십시오; 가격 세부 정보는 제품 페이지에서 확인할 수 있으며, 평가를 위해 임시 라이선스 페이지 에서 임시 라이선스를 얻을 수 있습니다.

자주 묻는 질문

Node.JS에서 PDF를 DOCX로 변환할 때 복잡한 레이아웃을 어떻게 처리하나요?
SDK는 기본적으로 원본 서식을 유지하려고 시도합니다. DocxConvertOptions의 preserveOriginalFormatting을 토글하여 정확성과 속도 사이의 균형을 맞출 수 있습니다. 모든 옵션은 API reference를 참조하세요.
PDF를 DOCX로 변환할 때 파일 크기 제한은 어떻게 되나요?
클라우드 서비스는 무료 계정의 경우 최대 200 MB까지 파일을 허용합니다; 더 큰 파일은 업그레이드된 플랜이 필요합니다. 업로드는 스트리밍 방식으로 이루어지므로 서버의 메모리 사용량이 낮게 유지됩니다.
한 번의 요청으로 여러 PDF를 DOCX로 변환할 수 있나요?
API는 요청당 하나의 문서만 처리하지만, Node.JS에서 파일 목록을 반복하고 병렬로 변환을 실행하여 계정의 동시성 제한을 준수할 수 있습니다.
유료 라이선스 없이 로컬에서 변환을 테스트할 방법이 있나요?
예, 임시 라이선스 페이지에서 임시 평가 라이선스를 요청할 수 있습니다. 이는 개발 및 테스트를 위한 전체 기능을 제공합니다.

nodejs conversion on Document Processing REST APIs | GroupDocs Cloud