AI 튜토리얼

Node.js에서 LibreOffice Kit으로 Office 문서를 PDF 및 PNG로 변환하기

@deepseek-ai/libreoffice-kit 설치, Office 파일을 PDF로 변환, 페이지를 PNG로 렌더링, 스프레드시트 재계산, 글꼴 구성, Node.js에서 플랫폼별 엔진 관리 방법을 알아보세요.

2026년 10월 1일약 14분 소요

Node.js에서 LibreOffice Kit으로 Office 문서를 PDF 및 PNG로 변환

개요

@deepseek-ai/libreoffice-kit은 미리 빌드되고 경량화된 LibreOffice 엔진을 사용해 Office 문서를 변환하고 렌더링하는 Node.js 패키지입니다. 별도로 설치된 LibreOffice에 의존하지 않고 예측 가능한 문서 레이아웃, 가독성 높은 텍스트, 명시적인 글꼴 제어, 오프라인 실행이 필요한 애플리케이션을 위해 설계되었습니다.

이 패키지는 Office 문서의 PDF 변환, 직접 PNG 렌더링, 스프레드시트 재계산을 지원합니다. Node.js 서비스, 데스크톱 애플리케이션, 일괄 처리 작업 또는 기타 문서 파이프라인에서 사용할 수 있습니다. 인증, 파일 저장, 미리보기 인터페이스는 애플리케이션이 담당합니다.

주요 기능

Office 변환: 지원되는 Writer, Calc, Impress 문서를 PDF로 내보냅니다.
페이지 렌더링: Office 또는 PDF 입력을 PNG 페이지로 직접 렌더링합니다.
스프레드시트 재계산: 통합 문서를 재계산하고 업데이트된 결과를 저장합니다.
글꼴 인식 처리: 시스템 글꼴을 검색하거나 명시적으로 구성된 글꼴 디렉터리를 색인화합니다.
구성 가능한 대체 글꼴: 일반적인 라틴 문자 및 중국어 간체 글꼴 제품군에 대한 대체 글꼴 기본 설정을 사용합니다.
누락 글꼴 보고: 읽을 수 있는 OOXML 문서 데이터에 선언된 글꼴 제품군 중 사용할 수 없는 항목을 보고합니다.
오프라인 엔진: 지원되는 macOS 및 Windows 시스템에서는 패키지된 네이티브 엔진을, Linux에서는 WASM 엔진을 사용합니다.
리소스 제어: 시간 제한과 글꼴 색인 또는 로드 제한을 적용합니다.
명령줄 및 Node API: 터미널에서 변환을 실행하거나 애플리케이션 코드에 통합합니다.

지원 문서 관련 사항

엔진은 Writer, Calc, Impress, OOXML 및 바이너리 Office 필터, 차트, 레이아웃 및 그리기 구성 요소, PDF 내보내기 기능을 유지합니다. 바이너리 .doc, .xls, .ppt 파일은 Microsoft Office 97–2003 파일과 같은 실제 OLE 복합 문서인 경우 지원됩니다.

바이너리 Office 확장자로 이름만 변경한 RTF 또는 HTML 파일은 허용되지 않습니다. .wps 파일도 허용되지 않습니다.

OOXML 문서의 경우 missingFonts는 읽을 수 있는 문서 XML에서 발견된 사용할 수 없는 글꼴 제품군을 보고합니다. 바이너리 형식은 LibreOffice가 자체적으로 글꼴을 계속 매칭하더라도 빈 목록을 반환합니다. 따라서 이 결과는 누락된 글리프를 완전히 보고하는 기능이 아닙니다.

사전 요구 사항 및 설치

Node.js 22.19.0 이상이 필요합니다. npm에서 버전 0.1.3을 설치합니다.

npm install @deepseek-ai/libreoffice-kit@0.1.3

이 패키지는 선택적 종속성을 사용해 현재 운영 체제 및 아키텍처에 맞는 엔진을 설치합니다. 설치 중 LibreOffice를 컴파일하거나 추가 엔진을 다운로드하지 않으며, 사용자가 설치한 LibreOffice 애플리케이션을 검색하지도 않습니다.

플랫폼별 엔진 선택

macOS Apple Silicon: @deepseek-ai/libreoffice-kit-darwin-arm64를 사용합니다.
macOS Intel: @deepseek-ai/libreoffice-kit-darwin-x64를 사용합니다.
Windows ARM64: @deepseek-ai/libreoffice-kit-win32-arm64를 사용하며 ARM64 Node.js와 Microsoft Visual C++ v14 ARM64 재배포 가능 패키지가 필요합니다.
Windows x64: @deepseek-ai/libreoffice-kit-win32-x64를 사용하며 Microsoft Visual C++ v14 x64 재배포 가능 패키지가 필요합니다.
Linux: 일반적으로 공유 @deepseek-ai/libreoffice-kit-wasm 엔진을 사용합니다.

macOS와 Windows는 각각에 맞는 네이티브 패키지가 필요하며 WASM으로 대체되지 않습니다. 필요한 엔진이 없거나 손상된 경우 createConverter는 unavailable 오류와 함께 거부됩니다. 변환에 실패해도 다른 엔진으로 자동 전환되지 않습니다.

명령줄 인터페이스 사용

설치하면 dsoffice 명령이 추가됩니다. 프로젝트에 로컬로 설치한 경우 npm exec을 통해 호출합니다.

페이지를 PNG로 렌더링

다음 명령은 DOCX 문서의 1페이지를 report-pages 출력 디렉터리에 렌더링합니다.

npm exec -- dsoffice render \
  --input report.docx \
  --output-dir report-pages \
  --pages 1

Office 문서를 PDF로 변환

npm exec -- dsoffice convert \
  --input report.docx \
  --output report.pdf

스프레드시트 재계산

수식을 계산하고 업데이트된 통합 문서를 저장해야 할 때 재계산 명령을 사용합니다.

npm exec -- dsoffice recalculate \
  --input budget.xlsx \
  --output recalculated.xlsx

Node.js API를 통한 문서 변환

애플리케이션에 통합하려면 createConverter를 가져오고, 변환기를 생성한 다음 작업을 실행하고, finally 블록에서 변환기를 해제합니다.

import { createConverter } from '@deepseek-ai/libreoffice-kit';

const converter = await createConverter({
  timeoutMs: 120_000,
});

try {
  const result = await converter.render({
    inputPath: '/private/work/document.docx',
    outputPath: '/private/work/document.pdf',
  });

  console.log('Backend:', result.backend);
  console.log('Missing fonts:', result.missingFonts);
} finally {
  await converter.dispose();
}

이 예제에서는 생성된 PDF가 outputPath에 기록됩니다. 반환된 결과에는 선택된 백엔드가 표시되며 문서에서 감지된 누락 글꼴 제품군 이름이 포함됩니다.

경로 및 출력 요구 사항

입력 및 출력 경로에는 절대 경로를 전달합니다.
호출하는 애플리케이션이 소유하고 제어하는 비공개 디렉터리를 사용합니다.
요청한 출력 파일은 이미 존재해서는 안 됩니다.
네이티브 프로세스, 워커, 프로필 및 임시 리소스를 정리할 수 있도록 finally 블록에서 정리를 수행합니다.

사용자 지정 글꼴 구성

기본적으로 패키지는 일반적인 시스템 및 사용자 글꼴 디렉터리에서 글꼴을 검색합니다. 대신 fontDirectories를 통해 검색 루트를 명시적으로 지정할 수 있습니다.

import { createConverter } from '@deepseek-ai/libreoffice-kit';

const converter = await createConverter({
  timeoutMs: 120_000,
  fontDirectories: [
    '/absolute/path/to/company-fonts',
    '/absolute/path/to/cjk-fonts',
  ],
});

try {
  const result = await converter.render({
    inputPath: '/private/work/presentation.pptx',
    outputPath: '/private/work/presentation.pdf',
  });

  if (result.missingFonts.length > 0) {
    console.log('Unavailable families:', result.missingFonts);
  }
} finally {
  await converter.dispose();
}

사용자 지정 글꼴 루트는 기본 검색 목록에 추가되는 것이 아니라 기본 목록을 대체합니다. 패키지는 fontkit을 사용해 메타데이터와 글리프 지원 범위를 검사한 다음, 선택한 파일을 원래 글꼴 바이트로 엔진에 전달합니다.

글꼴 모음은 번들에 포함되거나 다운로드되지 않습니다. 배포 환경에서 적절한 글꼴을 제공하고 해당 글꼴의 재배포 권한을 준수해야 합니다. 일반적으로 최소 구성 컨테이너에는 글꼴을 설치하거나 명시적인 글꼴 디렉터리를 구성해야 합니다.

대체 글꼴 동작

기본 fontFallbacks에는 일반적인 라틴 및 중국어 간체 글꼴군에 대한 우선순위가 포함되어 있습니다. Calibri를 사용할 수 없을 때의 대안으로 Carlito가, Cambria를 사용할 수 없을 때의 대안으로 Caladea가 포함됩니다. 호출자가 제공하는 대체 글꼴 그룹은 기본값을 대체하며, 실제로 사용 가능한 글꼴만 선택할 수 있습니다. 글꼴을 설치하지는 않습니다.

장식용 및 필기체 글꼴을 포함해 설치된 글꼴 패밀리가 정확히 일치하는 경우 우선적으로 사용됩니다. WASM 글꼴 요청에는 적절한 설치 글꼴 스타일을 선택할 수 있도록 굵기와 기울임 정보도 포함되며, 글꼴 카탈로그는 누락된 글리프를 위해 추가 글꼴을 제공할 수 있습니다.

고급 운영 팁

변환기 재사용 시 주의 사항

변환기를 재사용하면 변경되지 않은 글꼴 메타데이터에 대해 공유되는 메모리 내 캐시와 제한된 사용자 로컬 디스크 캐시의 이점을 얻을 수 있습니다. 그러나 하나의 변환기에서 수행되는 작업은 직렬화됩니다. 서비스에 특정한 동시성 모델이 필요한 경우 동일한 변환기에서 여러 렌더링이 동시에 실행된다고 가정하지 말고 이 직렬화를 고려해야 합니다.

각 렌더링은 여전히 새로운 네이티브 프로세스 또는 Node 워커와 비공개 프로필을 사용합니다. 취소 및 정리는 엔진 종료와 정리가 완료될 때까지 기다립니다.

글꼴 리소스 예산 설정

규모가 크거나 신뢰할 수 없는 글꼴 디렉터리는 사용 가능한 글꼴 제어 기능으로 제한해야 합니다.

maxFontFiles는 색인화할 글꼴 파일 수를 제한합니다.
maxFontFileBytes는 개별 글꼴 파일 크기를 제한합니다.
maxLoadedFontBytes는 로드되는 글꼴 데이터의 총량을 제한합니다.

모든 작업은 글꼴을 다시 검색하고 재검증합니다. 변경되지 않은 메타데이터는 변환기 팩토리 캐시를 통해 공유할 수 있습니다. 캐시 구성 및 무효화에 대한 자세한 내용은 글꼴 메타데이터 캐시 문서를 참조하세요.

Linux 글꼴 사용 가능성 계획

Linux WASM 엔진은 가져온 글꼴만 사용합니다. 사용 가능한 글꼴이 없으면 변환이 unavailable 오류와 함께 거부됩니다. 따라서 컨테이너에 적절한 글꼴을 설치하거나 제어된 글꼴 디렉터리를 마운트하고 해당 절대 경로를 fontDirectories에 전달해야 합니다.

Office와 출력이 동일하다고 가정하지 않기

글꼴을 고려한 처리는 패밀리 선택을 더 잘 제어할 수 있게 하지만, Microsoft Office와 동일한 출력이나 네이티브 엔진과 WASM 엔진 간에 동일한 출력을 보장하지는 않습니다. 글꼴 메트릭은 줄바꿈, 페이지 매김, 표 크기 및 기타 레이아웃 세부 사항에 영향을 줄 수 있습니다.

의미 있는 비교를 위해 동일한 문서 바이트, 글꼴 및 내보내기 옵션을 사용하세요. 네이티브 LibreOffice는 구성된 대체 글꼴보다 설치된 원본 패밀리와 메트릭 호환 대안을 먼저 선택할 수 있으며, 자체적으로 글꼴 스타일을 선택합니다.

변환을 문서 처리 경계로 취급하기

이 라이브러리는 변환 및 렌더링을 수행하지만, 권한 부여, 저장소 또는 미리보기 인터페이스는 제공하지 않습니다. 애플리케이션은 액세스를 검증하고, 호출자가 소유한 파일을 격리하며, 비공개 작업 디렉터리를 선택하고, 변환 작업에 적절한 시간 및 리소스 제한을 적용해야 합니다.

개발 및 검증

저장소 자체에 기여하는 경우 LibreOffice를 빌드하지 않고도 메타데이터, 단위 테스트 및 패키징 검사를 실행할 수 있습니다.

pnpm verify:metadata
pnpm test
pnpm test:packaging

실제 엔진 테스트에는 추가로 어댑터 빌드, 준비된 엔진 페이로드, 그리고 packages/entry/lib/index.js의 절대 경로를 가리키는 LIBREOFFICE_RUNTIME_ENTRY가 필요합니다. 엔진 빌드에는 저장소에서 고정한 소스 및 도구 체인 버전을 사용해야 합니다.

결론

@deepseek-ai/libreoffice-kit은 최신 Node.js 애플리케이션에 Office 변환, 스프레드시트 재계산 및 PNG 렌더링을 통합할 수 있는 실용적인 방법을 제공합니다. 이 패키지의 주요 장점은 오프라인으로 작동하는 준비된 네이티브 및 WASM 엔진과 명시적인 글꼴 처리를 결합한다는 점입니다. 안정적인 결과를 얻으려면 필요한 글꼴을 제공하고, 비공개 절대 경로를 사용하며, 적절한 제한을 설정하고, missingFonts를 확인하고, 사용 후에는 항상 변환기를 정리하세요.

취소, 자세한 오류 처리 및 추가 리소스 제어에 대해서는 Node API 문서를 참조하세요.