글자 자리에 상자만 찍혔습니다
이 블로그는 글마다 OG 이미지를 PNG로 미리 만들어 둡니다. SVG 템플릿에 제목, 카테고리 라벨, 설명을 넣고 resvg로 래스터화하는 방식입니다. 그런데 한국어 이미지에서는 제목, 라벨, 설명이 모두 네모 상자(흔히 tofu라고 부르는 그것)로 찍히고 있었습니다. 일부 글자가 아니라 한국어 텍스트 전부였습니다.
원인은 단순했습니다. resvg에는 로드된 폰트가 하나도 없었고, SVG는 Inter와 Arial을 요청하고 있었습니다. 두 폰트 모두 한글 글리프가 없습니다. 렌더러는 그릴 글자 모양을 찾지 못했고, 그 자리에 상자를 그렸습니다.
에러는 나지 않았습니다. PNG 파일은 정상적으로 만들어졌고 빌드도 막히지 않았습니다. 파일이 있다는 사실만으로는 그 안에 글자가 제대로 들어 있는지 알 수 없었습니다.
당신의 이미지 생성 코드는 지금 어떤 폰트 파일로 글자를 그리고 있는지, 코드 한 줄을 짚어서 보여줄 수 있나요?
왜 조용히 지나갔나
SVG의 font-family는 요청일 뿐 보장이 아닙니다. 렌더러가 그 이름의 폰트를 갖고 있지 않으면 다른 폰트를 찾고, 해당 글리프를 가진 폰트가 끝내 없으면 상자를 그립니다. 이 과정은 실패로 취급되지 않습니다. 결과물은 유효한 PNG이고, 크기도 형식도 정상입니다. 깨진 것은 사람이 눈으로 볼 때만 드러납니다.
당신이라면? 시스템 폰트 로드를 켜서 빨리 끝내겠습니까, 폰트 파일을 저장소에 넣겠습니까?
수정: 폰트를 저장소에 넣고 직접 지정
- Noto Sans KR(400, 700)과 JetBrains Mono Bold를 assets/fonts에 넣었습니다.
- resvg에 이 파일들을 명시적으로 로드하고, loadSystemFonts는 false로 두었습니다. 이유는 재현성입니다. 시스템 폰트에 기대면 빌드하는 머신마다 결과가 달라질 수 있습니다.
- OG PNG 90장을 전부 다시 만들었습니다.
비용도 있습니다. Noto Sans KR 파일 하나가 약 2.4MB라서 두 굵기를 합치면 약 4.9MB, JetBrains Mono가 약 270KB입니다. 이만큼이 저장소에 그대로 들어갔습니다.
다시 만든 결과, 한국어 이미지뿐 아니라 영어 이미지도 전부 바이트가 바뀌었습니다. 예를 들어 영어 홈 이미지는 49,571바이트에서 44,174바이트가 됐습니다. 폰트 로딩 방식을 바꾸면 언어와 상관없이 모든 이미지를 다시 그리게 된다는 점은 알아 두는 게 좋습니다.
자가진단 체크리스트
- 서버 쪽 이미지 렌더러(resvg, 헤드리스 브라우저 등)가 쓰는 폰트 파일이 코드에 명시돼 있나요, 아니면 SVG의 font-family 이름에만 기대고 있나요?
- 지정한 폰트가 실제로 쓰는 모든 문자(한글, 일본어, 기호)의 글리프를 갖고 있나요?
- 생성된 이미지 가운데 비영어 페이지 하나라도 직접 열어서 눈으로 확인한 적이 있나요?
솔직한 부분
이 커밋은 폰트를 고쳤을 뿐 재발을 막는 검사를 추가하지는 않았습니다. 변경 파일 목록에 테스트는 없습니다. 상자가 찍힌 이미지가 얼마나 오래 공개돼 있었는지, 그동안 공유된 링크의 미리보기가 각 플랫폼 캐시에 아직 남아 있는지는 기록에 없어서 모릅니다. 또 시스템 폰트를 꺼 두었기 때문에 번들한 세 폰트에 없는 문자가 제목에 들어오면 같은 증상이 다시 생길 수 있습니다. 그 경우가 실제로 있었는지는 아직 확인하지 않았습니다.