Node.JS에서 단계별 HTML을 DOCX로 변환하는 튜토리얼

Mon, 27 Jul 2026 10:59:23 +0000

풍부한 HTML 페이지를 편집 가능한 DOCX 파일로 변환하는 것은 보고 및 문서 자동화 워크플로우에서 자주 필요한 작업입니다. GroupDocs.Conversion Cloud SDK for Node.js는 개발자가 REST 기반 라이브러리를 통해 이 변환을 완전히 수행할 수 있게 해줍니다. 이 튜토리얼에서는 SDK를 설정하고, Node.JS에서 HTML을 DOCX로 변환하는 코드를 작성하며, cURL을 사용해 API를 호출하고, 최적의 결과를 위한 구성 옵션을 적용하는 방법을 살펴봅니다.

필수 조건 및 설정

시작하기 전에 다음을 확인하십시오:

개발 머신에 Node.js 14 이상 버전이 설치되어 있어야 합니다.
활성화된 GroupDocs.Conversion Cloud 계정(제품 페이지에서 무료 체험을 등록할 수 있습니다).
GroupDocs Cloud 대시보드에서 확인할 수 있는 Client ID와 Client Secret.
클라우드 REST API를 호출하기 위한 인터넷 연결.

npm을 통해 SDK를 설치합니다:

npm install groupdocs-conversion-cloud

코드 탐색이 필요하면 최신 패키지를 다운로드하고 GitHub에서 소스를 확인하세요:

다운로드 GroupDocs.Conversion Cloud SDK for Node.js

SDK를 설치하고 자격 증명이 준비되면 구현 단계로 넘어갈 수 있습니다.

Node.JS에서 HTML을 DOCX로 변환: 단계별 워크스루

아래는 각 논리적 단계를 보여주는 간결한 walkthrough입니다. 전체 소스 코드는 이후에 제공됩니다.

단계 1: Conversion API 클라이언트 초기화

ConversionApi의 인스턴스를 생성하고 인증을 구성합니다.

const { ConversionApi, Configuration } = require('groupdocs-conversion-cloud');

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

const conversionApi = new ConversionApi(config);

2단계: HTML 소스 파일 업로드

변환하려는 HTML 파일을 업로드하십시오. API는 변환에 사용할 파일 식별자를 반환합니다.

const fs = require('fs');
const path = require('path');

const htmlPath = path.resolve(__dirname, 'sample.html');
const fileBytes = fs.readFileSync(htmlPath);

const uploadResponse = await conversionApi.uploadFile({
    file: fileBytes,
    fileName: 'sample.html'
});
const sourceFileId = uploadResponse.id;

3단계: 변환 옵션 설정

HTML에서 폰트를 포함하거나 페이지 여백을 설정하는 등 DOCX‑특정 옵션을 구성합니다. 이 단계에서는 HTML에서 DOCX 생성 사용자 정의를 보여줍니다.

const convertSettings = {
    outputFormat: 'DOCX',
    options: {
        embedFonts: true,
        pageSize: 'A4',
        marginTop: 20,
        marginBottom: 20,
        marginLeft: 15,
        marginRight: 15
    }
};

4단계: 변환 실행

위에서 정의한 설정과 소스 파일 ID를 사용하여 convert 메서드를 호출합니다.

const convertResponse = await conversionApi.convert({
    fileId: sourceFileId,
    convertSettings: convertSettings
});
const docxFileId = convertResponse.id;

5단계: 결과 DOCX 다운로드

생성된 DOCX 파일을 가져와 로컬에 저장합니다.

const docxData = await conversionApi.downloadFile({ fileId: docxFileId });
fs.writeFileSync(path.resolve(__dirname, 'output.docx'), docxData);
console.log('DOCX file saved as output.docx');

위 단계는 GroupDocs.Conversion Cloud SDK를 사용한 Node.JS에서 HTML을 DOCX로 변환 전체 워크플로를 보여줍니다.

전체 코드 예제: HTML 콘텐츠에서 DOCX 생성

다음 프로그램은 모든 조각을 하나의 실행 가능한 스크립트로 결합합니다.

// Full working example for HTML to DOCX conversion using GroupDocs.Conversion Cloud SDK for Node.js

const { ConversionApi, Configuration } = require('groupdocs-conversion-cloud');
const fs = require('fs');
const path = require('path');

async function convertHtmlToDocx() {
    // 1. Configure the API client
    const config = new Configuration({
        clientId: 'YOUR_CLIENT_ID',
        clientSecret: 'YOUR_CLIENT_SECRET'
    });
    const conversionApi = new ConversionApi(config);

// 2. Read the HTML file
    const htmlPath = path.resolve(__dirname, 'sample.html');
    const htmlBytes = fs.readFileSync(htmlPath);

// 3. Upload the HTML file
    const uploadResult = await conversionApi.uploadFile({
        file: htmlBytes,
        fileName: 'sample.html'
    });
    const sourceFileId = uploadResult.id;

// 4. Define conversion settings
    const convertSettings = {
        outputFormat: 'DOCX',
        options: {
            embedFonts: true,
            pageSize: 'A4',
            marginTop: 20,
            marginBottom: 20,
            marginLeft: 15,
            marginRight: 15
        }
    };

// 5. Perform the conversion
    const convertResult = await conversionApi.convert({
        fileId: sourceFileId,
        convertSettings: convertSettings
    });
    const docxFileId = convertResult.id;

// 6. Download the DOCX file
    const docxBytes = await conversionApi.downloadFile({ fileId: docxFileId });
    const outputPath = path.resolve(__dirname, 'output.docx');
    fs.writeFileSync(outputPath, docxBytes);
    console.log(`Conversion successful. DOCX saved to ${outputPath}`);
}

// Execute the conversion
convertHtmlToDocx().catch(err => {
    console.error('Conversion failed:', err);
});

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

cURL 및 REST API를 사용한 변환 실행

HTTP를 직접 사용하고 싶다면, 다음 cURL 명령이 동일한 변환을 수행합니다.

액세스 토큰 얻기

YOUR_CLIENT_ID 및 YOUR_CLIENT_SECRET를 귀하의 자격 증명으로 교체하십시오.

curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

응답에 access_token이 포함됩니다.

HTML 파일 업로드

   curl -X POST "https://api.groupdocs.cloud/v2.0/storage/files/sample.html" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -F "file=@sample.html"

변환 시작

curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "sourceFilePath": "sample.html",
           "outputFilePath": "output.docx",
           "outputFormat": "DOCX",
           "options": {
               "embedFonts": true,
               "pageSize": "A4"
           }
         }'

변환된 DOCX 다운로드

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

전체 매개변수 목록은 공식 API 문서를 참조하십시오.

HTML 콘텐츠를 DOCX로 변환하기 위한 옵션 구성

SDK는 출력물을 미세 조정할 수 있는 여러 속성을 제공합니다:

embedFonts - 모든 참조된 글꼴을 DOCX에 포함시켜 시각적 일관성을 보장합니다.
pageSize - 페이지 크기를 설정합니다 (A4, Letter 등).
marginTop / marginBottom / marginLeft / marginRight - 포인트 단위로 페이지 여백을 조정합니다.

이 옵션을 적용하는 예:

const convertSettings = {
    outputFormat: 'DOCX',
    options: {
        embedFonts: true,
        pageSize: 'Letter',
        marginTop: 30,
        marginBottom: 30,
        marginLeft: 20,
        marginRight: 20
    }
};

전체 목록은 ConversionOptions class를 참조하십시오.

HTML 콘텐츠를 DOCX로 변환할 때 성능 고려 사항

대형 또는 복잡한 HTML 문서를 변환할 때는 다음 팁을 기억하세요:

API 클라이언트 재사용 - 각 파일마다 새로운 ConversionApi 인스턴스를 생성하면 오버헤드가 발생합니다.
대용량 HTML 파일 스트리밍 - 전체 파일을 메모리에 로드하는 대신 스트림(fs.createReadStream)과 SDK의 uploadFileStream 메서드를 사용합니다.
임베드된 리소스 제한 - 업로드 전에 HTML에서 불필요한 이미지나 스크립트를 제거하여 처리 시간을 줄입니다.
배치 변환 - 루프에서 파일을 순차적으로 처리하되, API 속도 제한을 준수하여 스로틀링을 방지합니다.

이러한 관행을 적용하면 낮은 지연 시간과 적당한 메모리 사용량을 유지하는 데 도움이 됩니다.

결론

Node.JS에서 HTML을 DOCX로 변환하는 작업이 GroupDocs.Conversion Cloud SDK for Node.js를 사용하면 간단해집니다. 위 단계들을 따라 하면 HTML에서 신뢰할 수 있는 DOCX 생성을 모든 서버‑사이드 애플리케이션에 통합하고, 출력물을 맞춤 설정하며, 대용량 작업에 대한 성능을 최적화할 수 있습니다. 프로덕션 사용을 위해 적절한 라이선스를 확보하는 것을 기억하세요; 구독을 구매하거나 임시 라이선스 페이지에서 임시 라이선스를 얻을 수 있습니다. 즐거운 코딩 되세요!

자주 묻는 질문

Node.JS에서 HTML을 DOCX로 변환을 시작하려면 어떻게 해야 하나요?

SDK를 사용하여 ConversionApi 클라이언트를 생성하고, HTML 파일을 업로드한 다음 원하는 변환 옵션을 설정하고 convert 메서드를 호출합니다. 이 프로세스는 완전히 비동기이며 다운로드를 위한 DOCX 파일 식별자를 반환합니다.

HTML에서 DOCX 생성에 대해 조정할 수 있는 옵션은 무엇인가요?

ConversionOptions 객체를 사용하면 글꼴을 포함하고, 페이지 크기를 선택하며, 여백을 설정하고, 이미지 처리를 제어할 수 있습니다. 모든 사용 가능한 설정은 API 참조를 확인하세요.

외부 CSS 또는 이미지를 포함하는 HTML을 변환할 수 있나요?

예. 변환을 시작하기 전에 모든 참조된 리소스(CSS, 이미지)를 동일한 스토리지 폴더에 업로드하면 SDK가 처리 중에 링크를 해결합니다.

프로덕션 배포에 라이선스가 필요합니까?

프로덕션에서는 유효한 라이선스가 필요합니다. 테스트용 임시 라이선스는 임시 라이선스 페이지에서 얻을 수 있으며, 라이브 환경으로 전환할 준비가 되면 전체 구독을 구매하십시오.

nodejs html docx on Document Processing REST APIs | GroupDocs Cloud