fix(seo): OG 이미지 함수 용량 제한 해소

Edge Function에 번들된 한글 폰트가 Vercel 배포 용량 제한을 초과했습니다.

OG Route Handler를 Node.js runtime으로 전환하고 폰트를 파일 시스템에서 지연 로드하도록 변경했습니다. 실제 폰트 PNG 테스트와 ADR로 배포 계약을 고정했습니다.

Author: dev-wooyeon

app/api/og/route.test.ts

@@ -1,45 +1,21 @@
 // @vitest-environment node
 
-import { readFile } from 'node:fs/promises';
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import { NextRequest } from 'next/server';
 
 const PNG_SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
 
-afterEach(() => {
-  vi.unstubAllGlobals();
-  vi.resetModules();
-});
-
 describe('GET /api/og', () => {
-  it('returns a non-empty PNG using the bundled Korean font', async () => {
-    vi.stubGlobal(
-      'fetch',
-      vi.fn(async (input: string | URL | Request) => {
-        const url =
-          input instanceof URL
-            ? input
-            : new URL(typeof input === 'string' ? input : input.url);
-
-        if (url.protocol !== 'file:') {
-          throw new Error(`Unexpected external font request: ${url.href}`);
-        }
-
-        return new Response(await readFile(url), {
-          status: 200,
-          headers: { 'Content-Type': 'font/ttf' },
-        });
-      })
-    );
-
-    const { GET } = await import('./route');
+  it('returns a non-empty PNG from the Node.js runtime', async () => {
+    const { GET, runtime } = await import('./route');
     const response = await GET(
       new NextRequest(
         'https://ark-log.vercel.app/api/og?title=%ED%95%9C%EA%B8%80%20OG%20%EC%9D%B4%EB%AF%B8%EC%A7%80&tags=Next.js,Ark'
       )
     );
     const bytes = new Uint8Array(await response.arrayBuffer());
 
+    expect(runtime).toBe('nodejs');
     expect(response.status).toBe(200);
     expect(response.headers.get('content-type')).toBe('image/png');
     expect(bytes.byteLength).toBeGreaterThan(10_000);

app/api/og/route.tsx

@@ -1,21 +1,22 @@
+import { readFile } from 'node:fs/promises';
 import { ImageResponse } from 'next/og';
 import type { NextRequest } from 'next/server';
 import { SITE_NAME } from '@/site/config/site';
 
-export const runtime = 'edge';
+export const runtime = 'nodejs';
 
 const fontUrl = new URL('./Pretendard-Bold.ttf', import.meta.url);
 let fontDataPromise: Promise<ArrayBuffer> | null = null;
 
 function loadFontData(): Promise<ArrayBuffer> {
   if (!fontDataPromise) {
-    fontDataPromise = fetch(fontUrl).then((response) => {
-      if (!response.ok) {
-        throw new Error(`Failed to load bundled OG font: ${response.status}`);
-      }
-
-      return response.arrayBuffer();
-    });
+    fontDataPromise = readFile(fontUrl).then(
+      (font) =>
+        font.buffer.slice(
+          font.byteOffset,
+          font.byteOffset + font.byteLength
+        ) as ArrayBuffer
+    );
   }
 
   return fontDataPromise;

docs/README.md

@@ -23,6 +23,7 @@ Last updated: 2026-07-13
 - `docs/adr/0022-default-new-posts-to-private.md`
 - `docs/adr/0023-run-the-release-quality-gate-in-ci.md`
 - `docs/adr/0024-use-latest-only-home-feed.md`
+- `docs/adr/0025-use-node-runtime-for-og-image-route.md`
 - `docs/blog-quality-guide.md`
 - `docs/database/db-schema.md`
 - `docs/database/supabase-view-count.sql`

docs/adr/0025-use-node-runtime-for-og-image-route.md

@@ -0,0 +1,46 @@
+# 0025. OG 이미지 route에 Node.js runtime을 사용한다
+
+Date: 2026-07-13
+Status: Accepted
+
+## 배경
+
+`/api/og`는 한글 제목을 안정적으로 렌더링하기 위해 2.72MB
+`Pretendard-Bold.ttf`를 번들에 포함한다. Edge runtime으로 생성한 Vercel
+함수는 1.86MB였고, Preview 배포의 1MB 제한을 초과했다. Next.js
+production build는 성공했지만 출력물을 배포하는 단계에서 실패했다.
+
+한글 글리프를 줄인 폰트 subset은 크기를 낮출 수 있지만, 블로그 제목과 태그에
+필요한 문자가 빠질 위험과 별도 생성 절차가 생긴다. 외부 URL에서 폰트를 읽으면
+함수 크기는 줄지만 OG 이미지 생성이 네트워크 상태에 의존한다.
+
+## 결정
+
+- `/api/og` Route Handler는 `nodejs` runtime을 명시한다.
+- 번들된 Pretendard 폰트는 `node:fs/promises`의 `readFile`로 지연 로드한다.
+- 폰트 데이터 Promise를 module scope에 캐시해 같은 인스턴스에서 반복해서
+  파일을 읽지 않는다.
+- route 테스트는 실제 번들 폰트로 PNG를 생성하고 Node.js runtime 설정을 함께
+  검증한다.
+- 배포 검증은 Vercel Preview가 `Ready` 상태인지와 실제 OG endpoint가 PNG를
+  반환하는지 확인한다.
+
+## 결과
+
+- Edge Function 크기 제한과 무관하게 전체 한글 폰트를 유지할 수 있다.
+- OG 이미지 생성에 외부 폰트 서버가 필요하지 않다.
+- Edge runtime 대비 실행 위치와 cold start 특성은 달라질 수 있다.
+- 폰트 파일 크기 자체는 저장소와 Node.js 함수 산출물에 남는다.
+
+## 검토한 대안
+
+- 한글 폰트 subset 생성: Edge runtime을 유지할 수 있지만 글리프 누락 방지와
+  생성 절차를 지속해서 관리해야 한다.
+- 외부 폰트 URL을 runtime에 fetch: Edge bundle은 작아지지만 네트워크 장애가
+  OG 이미지 생성 실패로 이어진다.
+- 커스텀 폰트 제거: 배포는 단순해지지만 한글 렌더링의 일관성과 기존 테스트
+  의도를 잃는다.
+
+## Related History
+
+- `5c4bcaf`: OG 이미지에 번들 한글 폰트 도입

docs/adr/README.md

@@ -42,6 +42,7 @@ ADR은 AI 협업 가이드와 별개의 문서다. 사람이 결정했든 AI가
 | [0022](0022-default-new-posts-to-private.md)                      | Accepted   | 새 글을 명시적으로 검토한 뒤 공개한다                        |
 | [0023](0023-run-the-release-quality-gate-in-ci.md)                | Accepted   | 배포 품질 gate를 CI에서 실행한다                             |
 | [0024](0024-use-latest-only-home-feed.md)                         | Accepted   | 홈 피드를 최신순 단일 경로로 유지한다                        |
+| [0025](0025-use-node-runtime-for-og-image-route.md)               | Accepted   | OG 이미지 route에 Node.js runtime을 사용한다                 |
 
 ## 작성 조건