Next.js · Cache Components

use cache 경계와 키

경계와 키가 만들어지는 과정을 함께 봅니다. cookies()는 경계 밖에서 읽어 인자로 넘기고, 안에서 읽으면 next-request-in-use-cache 오류가 발생합니다. 값을 바꾸면 바뀐 키 조각이 즉시 강조되고 HIT 또는 MISS로 나뉩니다.

개념 시각화 · Next.js 16.3.2 기준 · 실제 서버 실행이나 측정이 아닙니다공식 문서 ↗
인자

이 조합의 키는 처음입니다 — MISS. 계산 결과를 새 항목으로 저장했습니다. 같은 값으로 되돌리면 HIT가 됩니다.

  • 경계 안에서는 요청 API를 읽을 수 없다use-cache.md:194

    캐시된 함수·컴포넌트는 cookies(), headers(), searchParams에 접근할 수 없다. 제약은 호출 스택을 따라 전파되어, 캐시 함수가 부르는 헬퍼가 읽어도 next-request-in-use-cache로 똑같이 실패한다. 경계 밖에서 읽어 인자로 넘겨야 한다.

  • 키는 무엇으로 만들어지나use-cache.md:74-99

    Build ID + Function ID(함수의 위치·시그니처 해시) + 직렬화된 인자로 만들어진다. 개발 모드에서는 HMR 해시도 들어간다. 그래서 배포가 바뀌면 모든 항목이 무효가 되고, 인자가 하나만 달라도 별개의 항목이 된다.

  • 캡처한 외부 변수도 인자가 된다use-cache.md:82-99

    캐시된 함수가 바깥 스코프의 변수를 참조하면 그 변수가 자동으로 인자로 묶여 키에 포함된다. 의도치 않게 사용자별 값을 캡처하면 캐시가 사용자 수만큼 쪼개지므로, 무엇이 키에 들어가는지 항상 확인해야 한다.

  • 이 데모의 저장소는 단순화한 가정이다use-cache.md:198-215

    이 데모는 저장소가 계속 유지된다고 가정한다. 실제로 기본 인메모리 핸들러를 쓰는 서버리스 환경에서는 요청 간 보존이 보장되지 않지만, 자체 호스팅에서는 유지된다. 필요하면 use cache: remote로 전용 핸들러를 쓴다.