---
type: note
title: 'chore :: Obstacle -> (PdfjsDist, Unpdf)'
description: 'unpdf 는 브라우저 밖(Node·Bun·Cloudflare Workers)에서 PDF 텍스트·이미지를 꺼낼 때, pdfjs-dist 를 직접 쓰면 따라오는 배관 — 워커 설정, legacy 빌드 경고, Workers 의 빠진 전역과 막힌 WASM, 디코더 서빙, 텍스트 조각 잇기 — 을 미리 해둔 PDF.js 번들과 함수다. 대가는 워커 없이 내 이벤트 루프에서 파싱한다는 것, 범위는 꺼내기·그리기뿐이다.'
tags: ['pdf', 'pdfjs', 'serverless', 'cloudflare-workers']
status: release
ctime: 2026-11-12
mtime: 2026-11-12
sources:
  - id: unpdf-readme
    resource: https://github.com/unjs/unpdf/blob/f41a5d91d7b2ae0ca069c7dc279e9014b4eb706c/README.md
    title: 'unpdf — README'
  - id: unpdf-plugins
    resource: https://github.com/unjs/unpdf/blob/f41a5d91d7b2ae0ca069c7dc279e9014b4eb706c/src/pdfjs-serverless/rolldown/plugins.ts
    title: 'unpdf — rolldown/plugins.ts (PDF.js 소스 패치)'
  - id: unpdf-polyfills
    resource: https://github.com/unjs/unpdf/blob/f41a5d91d7b2ae0ca069c7dc279e9014b4eb706c/src/pdfjs-serverless/polyfills.mjs
    title: 'unpdf — polyfills.mjs'
  - id: unpdf-mocks
    resource: https://github.com/unjs/unpdf/blob/f41a5d91d7b2ae0ca069c7dc279e9014b4eb706c/src/pdfjs-serverless/mocks.mjs
    title: 'unpdf — mocks.mjs'
  - id: unpdf-decoders-workerd
    resource: https://github.com/unjs/unpdf/blob/f41a5d91d7b2ae0ca069c7dc279e9014b4eb706c/src/pdfjs-serverless/decoders/workerd.mjs
    title: 'unpdf — decoders/workerd.mjs'
generated: { by: claude/opus-5.5, at: 2026-11-12T00:00:00Z }
---

![브라우저 밖에서 PDF 의 텍스트나 이미지를 꺼내려고 PDF.js(pdfjs-dist)를 직접 쓰면 할 일이 따라온다. 워커 경로를 맞추거나 워커를 꺼야 하고, Node 에서는 legacy 빌드를 쓰라는 경고가 나오고, Cloudflare Workers 에는 PDF.js 가 쓰는 전역이 없고 실행 중 WASM 컴파일이 막혀 있으며, 이미지 디코더 WASM 을 URL 로 서빙해야 하고, 텍스트는 페이지를 돌며 조각을 이어 붙여야 한다. unpdf 는 이걸 미리 해둔 PDF.js 번들과 함수를 준다. import 하고 extractText 한 줄이면 된다.](/svg/unpdf_serverless_pdfjs.svg)

```haskell
-- 브라우저 밖에서 PDF 텍스트·이미지를 꺼낼 때, pdfjs-dist 를 직접 쓰면 따라오는 배관 → unpdf 에선
chore :: Obstacle -> (PdfjsDist, Unpdf)
chore Worker     = ("workerSrc 를 맞추거나 워커를 끈다",       "워커를 번들에 넣어 같은 스레드에서 돌린다")
chore NodeBuild  = ("\"legacy 빌드를 쓰라\" 경고",             "경고를 지우고, 빠진 최신 API 는 폴리필")
chore WorkersEnv = ("FinalizationRegistry·navigator 가 없다",  "PDF.js 보다 먼저 전역을 채운다")
chore WorkersWasm= ("실행 중 WASM 컴파일이 막혀 있다",          "JBIG2·JPEG 2000 디코더를 JS 판으로")
chore Decoders   = ("디코더 WASM 을 URL(wasmUrl)로 서빙한다",  "번들 조각으로 넣어두고 필요할 때만 불러온다")
chore TextLoop   = ("페이지를 돌며 텍스트 조각을 잇는다",       "extractText pdf { mergePages = True }")
  -- 나머지도 함수 하나씩: extractImages(PNG) · renderPageAsImage · inspectPages(스캔 페이지 → OCR 판단) · 링크 · 메타
  -- getDocumentProxy 로 한 번 열어 여러 함수에 넘기면 다시 파싱하지 않는다

-- 그래서 고르는 법
pick :: Need -> Where -> Library
pick (Create _) _   = Other              -- 꺼내기·그리기만 한다: 만들거나 고치는 함수가 없다
pick (Edit _)   _   = Other
pick _ Browser      = Either             -- pdfjs-dist 는 워커로 따로 돌고, unpdf 번들은 내 스레드에서 돈다
pick _ _            = Unpdf              -- Node 24+ · Bun · Cloudflare Workers. pdf-parse 의 대안 (README)

-- 대가: 워커가 없으니 파싱이 내 이벤트 루프에서 돈다 → 추출 호출을 타임아웃과 경주시킨다 (README)
-- 페이지를 이미지로 그리려면 @napi-rs/canvas 를 따로 설치한다 (선택적 peerDependency)
-- 다른 PDF.js(버전 고정 등)를 쓰려면: definePDFJSModule (\_ -> import "pdfjs-dist/legacy/build/pdf.mjs")
```
