이번 소식
Next.js 16.4.0-canary.56에 미리 생성한 목록에 없는 URL 값을 어떻게 처리할지 정하는 실험 API가 추가됐습니다. unstable_paramMatching과 unstable_generateParamMatching이 그 대상입니다. 웹사이트를 만드는 개발자를 위한 변경이며, Cache Components를 켠 프로젝트의 카나리 시험 버전에 포함돼 있습니다.
주요 변경
상품 번호나 언어처럼 URL에서 달라지는 부분을 매개변수라고 합니다. 기존 generateStaticParams는 빌드할 때 미리 만들 구체적인 값의 예시를 제공합니다. 새 API는 그 예시 목록과 별개로, 처음 들어오는 값의 처리 정책을 지정할 수 있게 합니다.
- 없는 주소로 처리:
not-found는 미리 정한 값 밖의 요청에 404를 돌려주는 정책입니다. - 생성을 기다리게 처리:
blocking은 필요한 화면이 아직 없으면 생성이 끝날 때까지 요청을 기다리게 합니다. - 기본 화면을 먼저 제공:
fallback은 상황에 맞는 기본 화면을 먼저 보내고 내용을 이어서 제공하는 경계를 지정합니다. - 미리 생성하지 않기:
dynamic은 해당 매개변수를 사전 생성 대상에서 제외합니다. 설정하지 않은 매개변수는 기존 추론 규칙을 유지합니다.
영향 대상과 활용
예를 들어 허용한 언어의 상품 목록만 제공하는 사이트를 생각할 수 있습니다. 언어 값은 정해진 범위 밖이면 404로 막고, 아직 만들어 두지 않은 상품 주소는 화면 생성을 기다리거나 기본 화면을 먼저 보여주는 식으로 구분할 수 있습니다. 어떤 주소를 미리 만들 것인지와, 미리 만들지 않은 주소를 방문했을 때의 경험을 따로 설명할 수 있다는 점이 핵심입니다.
정책은 상위 레이아웃에서 하위 페이지로 합쳐지며, 하위 설정이 직접 지정한 항목만 덮어씁니다. 비동기 함수인 unstable_generateParamMatching으로도 같은 형태의 정책을 반환할 수 있고, generateStaticParams와 독립적으로 실행됩니다. Cache Components 외에 별도의 추가 설정 플래그는 필요하지 않다고 구현 설명에 명시돼 있습니다.
사용 전 확인할 점
정책에는 URL 순서에 따른 제약이 있습니다. not-found를 지정한 매개변수 앞쪽도 모두 명시적으로 같은 정책이어야 합니다. 정적 파일로 내보내는 output: 'export'에서는 모든 매개변수에 not-found를 명시해야 합니다. 따라서 모드 이름만 바꿔 모든 경로에 자유롭게 적용할 수 있는 기능으로 보면 안 됩니다.
API 이름에 붙은 unstable과 카나리 상태를 고려해 별도 시험 환경에서 호환성을 확인할 변경입니다. 공식 PR에도 특정 배포 구성의 추가 검증 항목이 남아 있습니다. 이 글에서는 실제 애플리케이션의 빌드·배포 시험을 수행하지 않았습니다.
공식 출처·발표 시점
해당 릴리스 게시 시각은 2026년 10월 2일 09:07:46 KST입니다. 세부 동작과 제약은 릴리스가 연결한 공식 PR #97393에서 확인했습니다.
새 글 받아보기
RSS 리더에서 BlogFlow의 새 글을 확인할 수 있습니다.