Dev Note

pdf-lib 한글 PDF 글자 누락: subset:true와 fontkit long loca 버그

제가 만든 녹취록AI는 통화 녹음을 법원 제출용 녹취록 PDF로 만들어 줍니다. 처음에 쓰던 jsPDF는 기본 폰트에 한글 글리프가 없어 글자가 깨졌고, 그래서 PDF 생성을 서버로 옮겨 pdf-lib에 나눔명조 TTF를 직접 넣었습니다. 흔한 예제 그대로입니다.

pdf.registerFontkit(fontkit);
const font = await pdf.embedFont(fontBytes, { subset: true });

그런데 subset: true(문서에 쓴 글자만 남겨 넣는 옵션)를 켠 PDF에서 일부 글자가 빈칸으로 나왔습니다. 원인은 pdf-lib이 쓰는 fontkit 포크가 loca 오프셋을 2로 나누며 생기는 1바이트 오차였고, HarfBuzz로 미리 서브셋한 폰트를 subset: false로 넣어 해결했습니다. 그 과정에서 만난 함정 두 개까지 정리합니다.

증상: 글자 폭만큼 빈칸이 남는다

나눔명조 Regular를 subset: true로 넣고 "통화 녹음 1분 녹취록 화자", "안녕하세요 지난주에 말씀드렸던 계약 건"을 찍어 macOS PDF 렌더러로 그려 보면, 첫 줄은 "녹음"과 "녹"만, 둘째 줄은 "녕하세"와 "약 건"만 보입니다. 사라진 자리는 글자 폭만큼 비어 있습니다.

  • 빠지는 글자가 일정하지 않습니다. 위에서 멀쩡한 "통"이 다른 문서에서는 빠집니다. 숫자와 가운뎃점도 빠졌습니다.
  • 짧은 문서에서만 납니다. 서로 다른 음절 100개를 넣으면 85개가 깨졌는데 150개를 넣으면 하나도 깨지지 않았습니다. 긴 샘플로만 테스트하면 놓칩니다.
  • subset: false면 전부 정상이지만 한 쪽짜리 PDF가 1.4MB가 됩니다.

subset을 끄면 왜 1.4MB가 되나

PDF는 보는 쪽 기기에 폰트가 있다고 가정할 수 없어서 글리프를 파일 안에 넣습니다. PDF 표준 14 폰트에는 한글이 없으니 임베드는 사실상 필수입니다. 그런데 현대 한글은 완성형 음절만 11,172자이고 음절마다 외곽선이 따로 있습니다. 나눔명조 Regular는 글리프 14,538개, 파일 1,856,572바이트 중 외곽선을 담은 glyf 테이블이 1,737,728바이트입니다. Regular와 Bold를 통째로 넣으면 본문 424자짜리 한 쪽 예시 문서가 pdf-lib의 Flate 압축을 거치고도 1,432,236바이트입니다. 모바일에서 주고받을 파일로는 너무 커서 서브셋은 포기할 수 없었습니다.

먼저 배제한 것들

빈칸 증상의 후보는 여럿이지만 빠르게 걸러낼 수 있습니다. 폰트에 글자가 없는 경우라면 subset: false에서도 안 보여야 합니다. 텍스트가 NFD(자모 분리형)라면 text.normalize('NFC') !== text로 바로 드러납니다. 뷰어 문제인지는 PDF에 넣는 폰트를 fontkit으로 다시 읽어 보면 뷰어 없이 판정됩니다. 이 마지막 방법이 핵심 진단 도구였습니다.

// 예시: pdf-lib 이 내부에서 하는 서브셋을 fontkit 으로 똑같이 만들고, 다시 읽어 원본과 비교
const fontkit = require('@pdf-lib/fontkit');
const fs = require('fs');
const font = fontkit.create(fs.readFileSync('NanumMyeongjo-Regular.ttf'));
const text = '통화 녹음 1분 녹취록 화자';
const subset = font.createSubset();
const pairs = font.layout(text).glyphs.map((g) => [g, subset.includeGlyph(g)]);
const chunks = [];
subset.encodeStream()
  .on('data', (b) => chunks.push(Buffer.from(b)))
  .on('end', () => {
    const sub = fontkit.create(Buffer.concat(chunks));
    console.log('loca 형식', font.head.indexToLocFormat, '→', sub.head.indexToLocFormat);
    for (const [g, id] of pairs) {
      let same = false;
      try {
        same = sub.getGlyph(id).path.toSVG() === g.path.toSVG();
      } catch (e) {
        // 손상된 글리프는 다시 읽는 단계에서 예외가 나기도 한다
      }
      if (!same) console.log('손상:', String.fromCodePoint(...g.codePoints));
    }
  });
// 출력
// loca 형식 1 → 0
// 손상: 화 / 분 / 취 / 록 / 화 / 자

원본은 indexToLocFormat이 1(long)인데 서브셋은 0(short)으로 바뀌어 있었고, 공백을 포함한 글리프 10개 중 5개가 원본과 달랐습니다. 다른 문장에서는 다시 읽다가 Trying to access beyond buffer length 예외가 나는 글리프도 많았습니다. 뷰어가 아니라 폰트 파일 자체가 망가져 있었습니다. 이 에러 메시지는 뒤에서 다른 원인으로 한 번 더 나옵니다.

원인: loca 오프셋을 2로 나누는 순간

loca와 glyf

TrueType에서 외곽선은 glyf 테이블에 이어 붙어 있고, n번 글리프의 위치는 loca 테이블이 알려 줍니다. 데이터는 loca[n]부터 loca[n+1] 직전까지이고, 공백처럼 외곽선이 없으면 두 값이 같습니다. OpenType 명세는 head 테이블의 indexToLocFormat에 따라 두 형식을 둡니다.

indexToLocFormat형식저장하는 값표현 가능한 glyf 크기
0short (Offset16)실제 오프셋 ÷ 2최대 131,070바이트
1long (Offset32)실제 오프셋사실상 제한 없음

short는 2로 나눈 값을 저장하므로 짝수 오프셋만 표현할 수 있고, 그래서 short 형식 폰트는 모든 글리프 길이가 짝수입니다. long에는 그런 제약이 없습니다. glyf가 1.7MB인 나눔명조는 long 형식이고, 14,538개 중 2,890개 글리프의 길이가 홀수였습니다.

@pdf-lib/fontkit의 서브셋 코드

pdf-lib은 fontkit을 포크한 @pdf-lib/fontkit에 폰트 처리를 맡깁니다. 최신 버전 1.1.1의 TrueType 서브셋은 글리프 바이트를 패딩 없이 이어 붙이고, 마지막 오프셋이 0xFFFF 이하이면 short 형식을 골라 모든 오프셋을 2로 나눕니다.

// @pdf-lib/fontkit 1.1.1 (배포 번들에서 발췌)
// 서브셋: 글리프 바이트를 패딩 없이 이어 붙이며 누적 오프셋을 기록
this.glyf.push(buffer);
this.loca.offsets.push(this.offset);
this.offset += buffer.length;
// loca 인코딩: 마지막 오프셋이 0xFFFF 이하면 short 형식을 고르고 전부 2로 나눔
loca.preEncode = function () {
  if (this.version != null) return;
  this.version = this.offsets[this.offsets.length - 1] > 0xffff ? 1 : 0;
  if (this.version === 0) {
    for (var i = 0; i < this.offsets.length; i++) {
      this.offsets[i] >>>= 1;
    }
  }
};

패딩 없이 붙였으니 누적 오프셋이 홀수일 수 있고, >>>= 1은 그 나머지를 버립니다. 읽는 쪽은 2를 곱하므로 그 글리프는 1바이트 앞에서 시작하는 것으로 읽힙니다. 헤더의 첫 2바이트(윤곽선 개수)에 앞 글리프의 마지막 바이트가 섞이니 해석이 무너집니다. 진단 문장의 서브셋을 풀어 보면 이렇습니다.

글자글리프 길이실제 시작 위치저장 후 다시 읽은 위치
통37100
화377371370
(공백)0748748
녹284748748
음35010321032
17313821382
분39614551454
취32018511850
록38221712170
자22425532552

위치가 어긋난 다섯 글자가 진단 스크립트가 보고한 글자와 정확히 같습니다. 증상도 모두 설명됩니다. 어느 글리프가 홀수 위치에서 시작하는지는 앞에 놓인 글리프 길이 합의 홀짝으로 정해지므로, 같은 "통"도 문서마다 운명이 다릅니다. 서브셋의 glyf가 65,535바이트를 넘으면 long 형식이 선택되어 나누기가 없으니 긴 문서는 멀쩡합니다. 원본이 short 형식인 폰트는 길이가 전부 짝수라 안전합니다. 음절 수를 늘려 가며 재 보면 경계가 그대로 보입니다.

서로 다른 음절 수선택된 형식서브셋 glyf 크기손상된 글리프
50short21,980바이트43 / 50
100short45,578바이트85 / 100
150long70,272바이트0 / 150
200long90,523바이트0 / 200

제목과 표 머리글에만 쓰는 굵은 글씨 폰트는 글자 수가 적어 거의 항상 short 쪽으로 떨어집니다.

상위 fontkit은 2019년에 고쳤다

원본 fontkit은 이 문제를 PR #191(2019년 3월 병합)에서 고쳤습니다. 서브셋이 원본의 loca 형식을 그대로 쓰게 바꾼 수정입니다. 하지만 2020년 11월에 배포된 @pdf-lib/fontkit 1.1.1에는 이 수정이 없습니다. pdf-lib의 이슈 #1232는 2022년부터 열려 있고, 상위 변경을 가져오자는 포크 쪽 PR도 병합되지 않았습니다(2026년 11월 확인).

fontkit 2.0.4에는 수정이 들어 있지만, pdf-lib 1.17.1은 서브셋을 직렬화할 때 fontkit 2에 없는 encodeStream()을 호출해서 subset: true로 넣으면 _this.subset.encodeStream is not a function으로 실패합니다. 이슈 스레드에 언급된 커뮤니티 포크는 검증하지 않았습니다.

해결: HarfBuzz로 먼저 줄이고, pdf-lib에는 통째로 넣는다

서브셋을 pdf-lib 밖에서 하기로 했습니다. subset-font는 HarfBuzz의 서브셋 기능을 WebAssembly로 빌드한 harfbuzzjs를 감싼 Node 패키지입니다. 문서에 쓰인 글자만 남긴 TTF를 만들고 pdf-lib에는 subset: false로 넣습니다. 이때 pdf-lib은 받은 폰트 바이트를 그대로 넣으므로 작은 폰트는 작게 들어갑니다.

// fonts-server.ts (발췌)
import 'server-only';
import subsetFont from 'subset-font';
import { padGlyfTable } from '@/lib/export/ttf-pad';
/** 본문/굵은 글씨에 실제로 쓰이는 문자열을 넘기면 서브셋 폰트 한 쌍을 돌려준다 */
export async function prepareFonts(regularText: string, boldText: string): Promise<PdfFonts> {
  const [regularSrc, boldSrc] = await Promise.all([
    loadFont('NanumMyeongjo-Regular.ttf'),
    loadFont('NanumMyeongjo-Bold.ttf'),
  ]);
  // 숫자·구두점·기본 라틴은 항상 포함 (쪽 번호, 시각 등)
  const base = ' 0123456789:./-()[]【】「」·,?!%₩"\'_';
  const [regular, bold] = await Promise.all([
    subsetFont(regularSrc, regularText + base, { targetFormat: 'sfnt', dropTables: ['GSUB', 'GPOS', 'gasp'], keepFeatures: [] }),
    subsetFont(boldSrc, boldText + base, { targetFormat: 'sfnt', dropTables: ['GSUB', 'GPOS', 'gasp'], keepFeatures: [] }),
  ]);
  return { regular: padGlyfTable(new Uint8Array(regular)), bold: padGlyfTable(new Uint8Array(bold)) };
}
// pdf.ts (발췌)
pdf.registerFontkit(fontkit);
// 이미 서브셋된 폰트 — fontkit 의 자체 서브셋(long-loca 버그)은 쓰지 않는다
const regular = await pdf.embedFont(fonts.regular, { subset: false });
const bold = await pdf.embedFont(fonts.bold, { subset: false });

HarfBuzz도 short 형식을 골랐지만 홀수 길이 글리프 뒤에 1바이트를 채워 오프셋을 짝수로 맞춥니다. "통"은 371바이트에서 372바이트로, "화"는 377바이트에서 378바이트로 늘어 있었습니다.

  • 서브셋 입력은 렌더링과 같은 문서 모델에서 뽑습니다. 쪽 번호처럼 렌더링 중에 생기는 문자는 기본 문자열로 항상 넣습니다. pdf-lib은 폰트에 없는 글자를 만나도 예외 없이 0번 글리프(.notdef)를 찍고, 나눔명조의 .notdef는 외곽선이 없습니다. 입력에서 빠진 글자도 fontkit 버그와 똑같은 빈칸이 됩니다.
  • GSUB·GPOS를 뺐습니다. 완성형 한글 음절은 cmap만으로 글리프가 정해지므로 영향이 없지만, 옛한글이나 합자가 필요하면 다시 봐야 합니다.

두 번째 함정: 같은 에러, 다른 원인

HarfBuzz 서브셋을 넣자 이번에는 PDF를 만드는 도중에 RangeError: Trying to access beyond buffer length가 났고, 스택은 fontkit의 TTFGlyph._getCBox를 가리켰습니다. fontkit은 외곽선을 해석할 때(_decode)는 loca[n] === loca[n+1]이면 빈 글리프로 보고 돌아가지만, 바운딩 박스를 구할 때(_getCBox)는 이 확인 없이 10바이트 헤더를 읽습니다. 글자 폭을 구하는 _getMetrics가 이 함수를 부르므로 글자를 찍기만 해도 이 경로를 탑니다. 여기에 세 조건이 겹쳤습니다.

  1. 나눔명조에서 공백은 마지막 글리프(14,537번)이고 외곽선이 없습니다.
  2. HarfBuzz는 원본의 글리프 순서를 유지한 채 번호를 다시 매기므로 공백이 서브셋에서도 마지막이 되고, 시작 오프셋이 glyf 길이와 같습니다.
  3. 제가 확인한 HarfBuzz 출력에서는 모두 glyf가 파일 맨 끝 테이블이었습니다. 한 예시에서 glyf는 1,024바이트 위치부터 1,854바이트, 파일 전체는 2,880바이트였습니다.

그래서 공백의 헤더를 읽다가 파일 끝을 넘습니다. 원본 폰트는 glyf가 파일 맨 앞이라 넘친 읽기가 다음 테이블에 떨어질 뿐 예외가 나지 않았습니다. 해결은 glyf 끝에 0을 16바이트 붙이는 것입니다. loca는 그대로라 글리프 해석은 바뀌지 않고, 넘친 읽기는 0으로 된 헤더를 얻습니다. 뒤 테이블 위치가 밀리므로 테이블 디렉터리를 다시 씁니다.

// ttf-pad.ts
const PAD_BYTES = 16;
function align4(n: number): number {
  return (n + 3) & ~3;
}
export function padGlyfTable(font: Uint8Array): Uint8Array {
  const view = new DataView(font.buffer, font.byteOffset, font.byteLength);
  const numTables = view.getUint16(4);
  const entries: Array<{ tag: string; checksum: number; offset: number; length: number }> = [];
  for (let i = 0; i < numTables; i++) {
    const p = 12 + i * 16;
    const tag = String.fromCharCode(font[p], font[p + 1], font[p + 2], font[p + 3]);
    entries.push({ tag, checksum: view.getUint32(p + 4), offset: view.getUint32(p + 8), length: view.getUint32(p + 12) });
  }
  if (!entries.some((e) => e.tag === 'glyf')) return font;
  // 새 크기 계산 (디렉터리 뒤에 원래 순서대로 4바이트 정렬)
  const headerSize = 12 + numTables * 16;
  let total = align4(headerSize);
  const placed = entries.map((e) => {
    const length = e.tag === 'glyf' ? e.length + PAD_BYTES : e.length;
    const offset = total;
    total = align4(total + length);
    return { ...e, newOffset: offset, newLength: length };
  });
  const out = new Uint8Array(total);
  out.set(font.subarray(0, 12), 0);
  const outView = new DataView(out.buffer);
  placed.forEach((e, i) => {
    const p = 12 + i * 16;
    out.set(font.subarray(12 + i * 16, 12 + i * 16 + 4), p); // tag
    outView.setUint32(p + 4, e.checksum);
    outView.setUint32(p + 8, e.newOffset);
    outView.setUint32(p + 12, e.newLength);
    out.set(font.subarray(e.offset, e.offset + e.length), e.newOffset);
  });
  return out;
}

0 바이트는 32비트 합으로 계산하는 테이블 체크섬을 바꾸지 않으므로 각 테이블 체크섬은 그대로 유효합니다. 파일 전체 체크섬(head.checkSumAdjustment)은 갱신하지 않았지만 아래 검증에서 문제는 없었습니다. 폰트를 바꾸면 공백의 글리프 번호가 달라질 수 있어서, 공백이 들어간 문자열로 테스트를 걸어 두었습니다.

it('HarfBuzz 서브셋 폰트의 마지막 빈 글리프도 fontkit 이 읽을 수 있게 된다', async () => {
  const src = readFileSync(path.join(process.cwd(), 'assets/fonts/NanumMyeongjo-Regular.ttf'));
  const sub = await subsetFont(src, '통화 녹음 1분 ', { targetFormat: 'sfnt', dropTables: ['GSUB', 'GPOS', 'gasp'], keepFeatures: [] });
  const padded = padGlyfTable(new Uint8Array(sub));
  expect(padded.byteLength).toBeGreaterThan(sub.byteLength);
  const font = fontkit.create(padded as unknown as Buffer);
  const run = font.layout('통화 녹음 1분 ');
  expect(run.glyphs.length).toBe(9);
  for (const g of run.glyphs) expect(() => g.cbox).not.toThrow();
});

Next.js에서 돌리기: serverExternalPackages

로컬 스크립트에서 돌던 코드가 Next.js 라우트 핸들러에서는 한 번 더 막힙니다. subset-font는 wasm을 readFile(require.resolve('harfbuzzjs/hb-subset.wasm'))로 읽는데, Next.js는 라우트 핸들러의 의존성을 기본적으로 번들에 묶고 16부터는 기본 번들러가 Turbopack입니다. 번들 안에서는 이 경로가 실제 wasm 파일로 제대로 풀리지 않았습니다. 해당 패키지를 번들에서 빼고 Node의 require로 직접 불러오게 하는 설정이 serverExternalPackages입니다. 또 배포 번들에는 파일 추적으로 찾은 파일만 들어가는데, 폰트는 런타임에 조립한 경로로 읽으므로 outputFileTracingIncludes로 폰트와 wasm을 명시했습니다.

// next.config.ts (발췌)
const nextConfig: NextConfig = {
  // HarfBuzz(subset-font)는 런타임에 require.resolve 로 wasm 을 찾으므로 번들하지 않고 Node 가 직접 로드하게 둔다
  serverExternalPackages: ['subset-font', 'harfbuzzjs', 'fontverter'],
  // PDF 생성 함수가 폰트 파일과 HarfBuzz wasm 을 배포 번들에 포함하도록 (Vercel 파일 추적)
  outputFileTracingIncludes: {
    '/api/transcripts/[id]/pdf': ['./assets/fonts/**', './node_modules/harfbuzzjs/hb-subset.wasm'],
  },
};
// app/api/transcripts/[id]/pdf/route.ts
export const runtime = 'nodejs';
  • Edge 런타임에서는 Node 파일 시스템 API를 쓸 수 없고 outputFileTracingIncludes도 적용되지 않으므로 Node 런타임으로 고정합니다.
  • 폰트 모듈에 import 'server-only'를 두어, 1.9MB짜리 원본 폰트를 읽는 코드가 클라이언트 쪽에서 import되면 빌드가 실패하게 했습니다.
  • subset-font는 wasm을 프로세스당 한 번만 초기화하고 서브셋 호출을 한 번에 하나씩(p-limit(1)) 처리하므로, Regular와 Bold를 Promise.all로 묶어도 실제로는 차례로 돕니다.

검증

같은 예시 문서로 세 방식을 비교했습니다. 손상 개수는 본문 폰트 기준입니다.

방식PDF 크기결과
원본 폰트 통째 (subset: false)1,432,236바이트정상
pdf-lib 내장 서브셋 (subset: true)21,751바이트글리프 139개 중 62개 손상
HarfBuzz 서브셋 + glyf 패딩24,392바이트138자 모두 원본과 일치

"일치"는 서브셋 폰트를 fontkit으로 다시 읽어 글자마다 외곽선과 글자 폭을 원본과 비교한 결과이고, macOS 렌더러로 뽑은 이미지와 앱에서 만든 2쪽짜리 PDF로 눈으로도 확인했습니다. 내장 서브셋보다 2.6KB 크지만 원본을 통째로 넣을 때의 약 59분의 1입니다.

같은 문제를 피하는 체크리스트

  • pdf-lib과 @pdf-lib/fontkit으로 TrueType 폰트를 subset: true로 넣는다면 fontkit.create(buf).head.indexToLocFormat부터 봅니다. 1이면 이 버그의 조건을 갖춘 것입니다.
  • 테스트 문서는 짧게, 공백을 넣어서 만듭니다. 긴 문서는 첫 번째 버그를, 공백 없는 문자열은 두 번째 버그를 가립니다.
  • 눈으로 판정하지 말고 넣은 폰트를 다시 파싱해 원본 글리프와 비교합니다. 서브셋 손상, 입력 누락, NFD가 구분됩니다.
  • pdf-lib에는 미리 서브셋한 폰트를 subset: false로 넣고, glyf 끝에 여백을 둡니다. 폰트를 바꾸면 테스트부터 다시 돌립니다.
  • Next.js에서는 serverExternalPackages, outputFileTracingIncludes, Node 런타임을 함께 챙깁니다.

가장 큰 교훈은 포크에 관한 것입니다. 2019년에 상위에서 고쳐진 버그가 2020년에 배포된 포크에는 없었습니다. 패키지 이름에 상위 프로젝트 이름이 들어 있어도 상위의 수정까지 따라온다는 보장은 없고, 용량을 줄이는 옵션도 결과가 맞는지 검증해야 할 대상입니다.

녹취록AI — 통화 녹음을 올리면 화자 분리와 타임스탬프를 거쳐 법원 제출 서식의 녹취록으로 정리하고, PDF와 Word로 내보낼 수 있습니다. 웹에서 열기
← 블로그 목록으로