NotionNext 문서

Appearance

빌드 성능과 Notion API rate limit(환경 변수) ​

yarn build, yarn export, Cloudflare Pages, Netlify, VPS 등 CI에서 Notion 데이터를 가져오는 상황에 적용됩니다. 구현: lib/build/buildEnv.js · 빌드 로그 키워드 [BuildEnv]

배경 ​

정적 내보내기(EXPORT=true) 시 NotionNext는 다음 작업을 수행합니다.

  1. 전체 prefetch: 경로를 생성하기 전에 사이트 안의 모든 글에 대해 block을 가져오고 빌드 캐시에 기록합니다(lib/build/prefetch.js).
  2. 페이지별 SSG: 각 route에 대해 HTML을 생성합니다. 단일 페이지가 Notion 데이터를 너무 느리게 가져오면 Next.js 기본 300초 제한(staticPageGenerationTimeout)에 걸릴 수 있습니다.

빌드 단계에서 Notion에 접근할 때는 RateLimiter(lib/db/notion/RateLimiter.ts)를 거칩니다. 기본값은 약 분당 50회, 인접 요청 사이 최소 300ms이며, prefetch concurrency와 함께 전체 소요 시간을 결정합니다.

자주 보이는 오류:

text
Sending SIGTERM signal to Next.js build worker due to timeout of 300 seconds
[API<<--response] duration:8336ms - from:prefetch

다국어 NOTION_PAGE_ID에 쉼표로 많은 사이트를 연결한 경우, 이전 버전의 빌드 캐시에서 ENAMETOOLONG: name too long 오류가 날 수 있습니다. lock file 또는 cache file 이름이 너무 길기 때문입니다. **4.9.5.3+**에서는 캐시 경로를 SHA-256 짧은 이름으로 처리합니다. 업그레이드 후 다시 배포하면 되며, 환경 변수를 짧게 줄일 필요는 없습니다.

환경 변수 목록 ​

배포 플랫폼(Cloudflare Pages -> Settings -> Environment variables) 또는 로컬 .env.local에 설정합니다. 빌드 시점에 적용되며 NEXT_PUBLIC_ 접두사는 필요하지 않습니다.

변수기본값설명
BUILD_PREFETCH_ENABLEDtrue(미설정 시 활성화)false, 0, off, skip 등으로 설정하면 전체 block prefetch를 비활성화합니다
BUILD_PREFETCH_CONCURRENCY8prefetch concurrency(1-32). Notion API가 느리면 2-4로 낮출 수 있습니다
NOTION_BUILD_RATE_MAX_PER_MINUTE50빌드 중 Notion에 보낼 수 있는 분당 최대 요청 수(1-600)
NOTION_BUILD_RATE_MIN_INTERVAL_MS300빌드 중 두 요청 사이의 최소 간격(ms, 0-60000). 값이 클수록 느리지만 rate limit에 덜 걸립니다
STATIC_PAGE_GENERATION_TIMEOUT300Next.js 단일 페이지 정적 생성 timeout(초, 60-3600). 글이 특히 크거나 API가 느리면 600 이상으로 설정할 수 있습니다

적용 여부 확인 ​

yarn build 또는 yarn export 실행 시 로그 시작 부분에 다음과 같은 JSON 한 줄이 나타납니다.

text
[BuildEnv] {"prefetchEnabled":false,"prefetchConcurrency":8,"notionRateMaxPerMinute":50,"notionRateMinIntervalMs":300,"staticPageGenerationTimeoutSec":600}

플랫폼에 설정한 값과 다르다면 변수가 Production 환경에 설정되어 있는지, 철자가 맞는지, 재배포가 필요한지 확인하세요.

권장 설정 ​

Cloudflare Pages / 글 많음 / API 단일 요청 >5s ​

먼저 전체 prefetch를 비활성화하고 단일 페이지 timeout을 늘립니다.

env
BUILD_PREFETCH_ENABLED=false
STATIC_PAGE_GENERATION_TIMEOUT=600

prefetch를 끄면 각 페이지가 SSG 단계에서 필요할 때 Notion 데이터를 가져옵니다. 전체 시간은 여전히 길 수 있지만, prefetch 단계에서 단일 worker의 300초 제한에 걸릴 가능성은 줄어듭니다.

prefetch는 유지하되 전체 속도를 낮추기 ​

env
BUILD_PREFETCH_ENABLED=true
BUILD_PREFETCH_CONCURRENCY=2
NOTION_BUILD_RATE_MAX_PER_MINUTE=30
NOTION_BUILD_RATE_MIN_INTERVAL_MS=500
STATIC_PAGE_GENERATION_TIMEOUT=600

Vercel / 빠른 로컬 머신 ​

대부분은 수정할 필요가 없습니다. 간헐적으로 timeout이 발생하면 먼저 아래만 조정하세요.

env
STATIC_PAGE_GENERATION_TIMEOUT=600

ENABLE_CACHE와의 관계 ​

변수단계
ENABLE_CACHE개발 / 프로덕션 런타임에서 파일+메모리 캐시 사용 여부(전체 사이트 설정 인덱스 참고)
BUILD_PREFETCH_* / NOTION_BUILD_RATE_*BUILD_MODE=true 또는 EXPORT=true 빌드와 내보내기에서만 적용

빌드 캐시 디렉터리는 lib/cache/build_session.js, .next/cache/notion을 참고하세요.

페이지 데이터 용량 점검 ​

4.10.0부터 프로덕션 빌드 후 Next.js 페이지 데이터 용량을 점검할 수 있습니다.

bash
yarn build
yarn perf:page-data

스크립트는 .next/server/pages/*.json을 스캔하고 .perf/page-data-budget.json에 보고서를 작성합니다. 기본 예산은 128KB이며, overBudgetPages가 0이면 현재 빌드에 기본 예산을 초과한 페이지가 없다는 뜻입니다.

선택 가능한 환경 변수:

bash
PERF_PAGE_DATA_WARN_KB=160 yarn perf:page-data
PERF_PAGE_DATA_FAIL=true yarn perf:page-data

사이트 콘텐츠가 많거나 글 목록이 길거나 POST_LIST_PREVIEW를 켜면 페이지 데이터가 커질 수 있습니다. 보고서에서 홈페이지나 목록 페이지가 예산을 초과하면, 전체 blockMap, 본문 전문 또는 불필요한 설정을 클라이언트로 전달하고 있지 않은지 우선 확인하세요.

관련 문서 ​

원문 / 유지보수 ​

동작이 변경되면 이 문서와 .env.example을 함께 업데이트하세요. 코드 진입점: lib/build/buildEnv.js.