Next.js 16.3.0-canary.106의 useCache deprecation 경고와 hybrid not-found 수정 이해하기

학습 목표·선수 지식: 두 canary 수정의 실제 적용 조건을 구분합니다. 선수 지식: next.config와 두 라우터.

• Next.js 16.3.0-canary.106에서 확인할 변경점
• useCache deprecation 경고의 의미
• hybrid not-found 수정이 중요한 이유
• 실무 업그레이드 점검 순서
• 적용 여부를 결정하는 기준
• 정리

Next.js 16.3.0-canary.106에서 확인할 변경점

Next.js 16.3.0-canary.106을 볼 때 가장 먼저 구분해야 할 것은 이 버전이 stable 릴리스가 아니라 canary 채널이라는 점입니다. canary는 곧바로 운영 반영을 전제로 읽기보다, 앞으로 바뀔 동작과 경고를 미리 확인하는 채널에 가깝습니다. 따라서 이번 변경도 “지금 모든 코드를 바꿔야 한다”는 신호가 아니라, 공식 태그와 릴리스 노트에서 해당 변경이 실제로 포함됐는지 대조한 뒤 “현재 프로젝트가 향후 변경에 얼마나 준비되어 있는지 확인하라”는 신호로 읽는 편이 안전합니다.

canary 릴리스를 읽을 때 주의할 점

Next.js의 canary 버전은 프레임워크 내부 동작, 실험적 API, 경고 메시지, 라우팅 처리 방식이 비교적 빠르게 바뀔 수 있습니다. 특히 App Router, Server Component, 캐시 계층, not-found 처리처럼 빌드 시점과 런타임 동작이 맞물리는 영역은 작은 수정도 실제 화면에서는 다르게 보일 수 있습니다. 그래서 릴리스 노트를 읽을 때는 변경 문장만 보지 말고, 내 프로젝트에서 해당 흐름이 어디에 걸려 있는지 함께 봐야 합니다.

이번 글에서 다루는 범위

이 글은 두 가지에 집중합니다. 첫째, useCache 관련 deprecation 경고가 실무 코드에서 어떤 의미를 갖는지 설명합니다. 둘째, hybrid not-found 수정이 App Router 기반 서비스의 404 처리와 어떤 관련이 있는지 정리합니다. 세부 내부 구현을 단정하기보다, 실제 프로젝트에서 확인해야 할 로그, 라우트, 테스트 시나리오를 중심으로 접근합니다.

공식 변경 근거를 확인하는 방법

이처럼 특정 canary 버전을 다룰 때는 글을 발행하기 전에 vercel/next.js 저장소의 릴리스, 태그, 비교 화면을 함께 확인해야 합니다. 확인 기준일을 문서에 남기고, useCache deprecation과 hybrid not-found가 같은 태그에 포함된 변경인지, 아니면 인접한 canary나 preview 브랜치에서 관찰한 변경인지 구분해야 합니다. PR 번호나 커밋 해시를 확인할 수 있다면 운영 판단 문장에는 그 근거를 함께 붙이는 편이 좋습니다.

useCache deprecation 경고의 의미

여기서 useCache는 애플리케이션에서 호출하는 Hook이나 함수가 아니라 next.config의 experimental.useCache 설정입니다. 'use cache' 지시어와 이름을 구분해야 합니다. 공식 마이그레이션 문서는 기존 experimental.useCache·experimental.dynamicIO 설정을 cacheComponents가 대체한다고 설명합니다.

설정 파일과 설정 래퍼부터 확인하기

next.config.js·next.config.ts와 설정을 합성하는 플러그인에서 experimental.useCache를 검색하세요. 페이지에서 useCache() 호출을 찾는 방식으로 이 경고를 진단하지 않습니다.

// next.config.ts — Cache Components 전환 예시
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
};
export default nextConfig;

이 코드는 완성된 이전 절차 전체가 아닙니다. 기존 experimental.useCache 설정을 제거하고, 나머지 프로젝트 설정은 보존합니다. Cache Components를 켜면 렌더링·캐시 모델도 바뀌므로 기존 dynamic·revalidate·fetchCache 라우트 설정, 요청 시 데이터 접근과 Suspense 경계를 공식 가이드에 따라 함께 검증해야 합니다. 경고를 숨기기 위해 설정 이름만 기계적으로 바꾸지 마세요.

hybrid not-found 수정이 중요한 이유

hybrid not-found라는 변경 제목만으로 모든 정적·동적 혼합 렌더링이나 모든 404 문제가 수정됐다고 단정할 수 없습니다. 정확한 대상은 공식 릴리스와 관련 PR #96392의 코드·테스트에서 확인해야 합니다. 릴리스 제목만으로 적용 범위를 넓혀 해석하지 마세요.

프로젝트에서 확인할 라우팅 조건

Pages Router와 App Router를 함께 사용하는지, 별도 배포 어댑터가 있는지, 실제로 어느 not-found 화면과 응답 상태가 나오는지 기록합니다. 일반적인 notFound 사용법과 특정 canary의 내부 버그 수정은 별도 항목으로 검증하세요.

// getPost와 ArticleView는 프로젝트에서 정의하는 모듈입니다.
import { notFound } from "next/navigation";

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPost(slug);
  if (!post) notFound();
  return <ArticleView post={post} />;
}

위 코드는 데이터가 없을 때 notFound를 호출하는 일반적인 발췌 예제입니다. 이 예제만으로 PR의 버그를 재현하거나 수정 여부를 증명하지는 못합니다. 같은 어댑터·라우터 구성에서 정상 URL과 없는 URL의 화면, 직접 접근, 클라이언트 이동, 응답 상태를 이전 버전과 비교해야 합니다.

실무 업그레이드 점검 순서

Next.js 16.3.0-canary.106을 시험하려면 운영 브랜치에 바로 올리기보다 별도 브랜치와 재현 가능한 환경을 먼저 준비하는 편이 좋습니다. 핵심은 업그레이드 자체가 아니라 업그레이드 전후 차이를 비교할 수 있는 상태를 만드는 것입니다. 경고 로그, 라우팅 결과, 빌드 산출물, 주요 페이지의 응답 상태를 같은 기준으로 남겨야 합니다.

경고 로그 확인

먼저 개발 서버와 빌드에서 경고가 다르게 나타나는지 확인합니다. next dev에서는 보이지 않던 경고가 next build에서만 보일 수 있고, 반대로 특정 페이지를 브라우저로 접근해야 재현되는 경고도 있습니다. 가능하면 로컬에서 한 번, CI에서 한 번 확인해 환경 차이를 줄이는 것이 좋습니다.

npm install next@16.3.0-canary.106
npm run build
npm run test
npm run lint

명령 실행 후에는 useCache, deprecated, not-found, notFound, cache 같은 문자열을 기준으로 로그를 분류합니다. 모든 경고를 즉시 수정하려고 하기보다, 애플리케이션 코드에서 발생한 경고와 외부 의존성에서 발생한 경고를 나누는 것이 먼저입니다.

라우트별 404 테스트

404 테스트는 단순히 존재하지 않는 URL 하나를 열어보는 것으로는 부족합니다. 정상 데이터가 있는 상세 페이지, 삭제된 데이터의 상세 페이지, 형식은 맞지만 실제 데이터가 없는 slug, 형식 자체가 잘못된 경로를 각각 확인해야 합니다. 또한 not-found.tsx가 루트에 있는지, 세그먼트 내부에 있는지에 따라 표시되는 화면이 달라질 수 있으므로 라우트 그룹별로 나누어 테스트하는 편이 좋습니다.

• 정상 slug에서 기대한 콘텐츠와 상태 코드가 유지되는지 확인합니다.
• 없는 slug에서 올바른 not-found.tsx가 표시되는지 확인합니다.
• generateStaticParams에 없는 값이 동적 처리되는지, 또는 404가 되는지 확인합니다.
• 캐시 삭제 또는 재검증 후에도 같은 결과가 나오는지 확인합니다.

CI와 배포 전 검증

CI에서는 경고를 단순 출력으로 남길지, 특정 경고를 실패 조건으로 볼지 결정해야 합니다. canary 검증 단계에서는 모든 경고를 실패로 만들면 실험이 어려울 수 있습니다. 대신 useCache 경고 개수, 발생 파일, 신규 경고 여부를 기록해 추세를 보는 방식이 현실적입니다. 배포 전에는 프리뷰 환경에서 404 관련 URL을 직접 확인하고, 로그 수집 도구에서 응답 상태가 의도대로 기록되는지 확인합니다. 이때 릴리스 확인 기준일, 비교한 태그, 관련 PR 번호를 작업 기록에 남기면 나중에 같은 경고가 재등장했을 때 원인 추적이 쉬워집니다.

적용 여부를 결정하는 기준

canary 버전을 적용할지 말지는 “새 버전이 나왔는가”가 아니라 “지금 이 변경을 검증할 이유가 있는가”로 결정하는 편이 좋습니다. 특정 버그 수정이 현재 서비스의 문제와 직접 연결되어 있다면 시험할 가치가 있습니다. 반대로 현재 서비스가 안정적으로 동작하고 있고, 이번 변경이 직접적인 문제를 해결하지 않는다면 stable 릴리스를 기다리는 것이 더 나을 수 있습니다.

canary를 써도 되는 상황

canary 적용이 합리적인 상황은 비교적 분명합니다. 이미 not-found 처리에서 재현 가능한 문제가 있고, 해당 수정이 그 문제와 관련되어 보이며, 프리뷰 환경과 회귀 테스트가 준비되어 있다면 검토할 수 있습니다. 또한 프레임워크 변경을 빠르게 추적해야 하는 플랫폼 팀이나 디자인 시스템 팀이라면 useCache 경고를 미리 파악하는 목적만으로도 별도 브랜치에서 테스트할 가치가 있습니다.

stable을 기다리는 것이 나은 상황

반대로 운영 서비스가 민감하고, App Router의 라우팅 테스트가 충분하지 않거나, 캐시 계층이 복잡한데 소유자가 불분명하다면 stable을 기다리는 편이 낫습니다. 특히 결제, 인증, 관리자 승인, 권한 기반 문서 접근처럼 실패 상태가 곧 사용자 신뢰와 연결되는 화면에서는 작은 라우팅 차이도 비용이 큽니다. 이 경우에는 canary를 운영에 넣기보다 테스트 브랜치에서 경고와 라우트 결과만 수집하는 방식이 더 적절합니다.

이 태그의 두 PR을 직접 연결합니다

2026-08-01 공개된 v16.3.0-canary.106 기록에서 #96448은 experimental.useCache 경고, #96392는 Pages Router와 App Router를 함께 사용하는 앱의 not-found 처리 및 adapter 경로와 연결됩니다. 이 글은 이 과거 태그의 변경을 설명하며 최신 운영 패치라는 뜻이 아닙니다.

이번 보완은 공식 릴리스·PR 기록을 확인했으며 canary를 설치해 해당 adapter 버그를 재현하지는 않았습니다. npm run test와 npm run lint는 프로젝트 scripts에 있을 때만 실행합니다. 없는 스크립트를 프레임워크 기본 제공 명령처럼 취급하지 않습니다.

정리

Next.js 16.3.0-canary.106에서 볼 핵심은 useCache 관련 deprecation 경고와 hybrid not-found 수정입니다. useCache 경고는 당장 장애를 뜻한다기보다 향후 변경에 대비해 캐시 사용 지점을 확인하라는 신호로 보는 것이 좋습니다. hybrid not-found 수정의 실제 영향은 관련 PR이 다루는 라우터·배포 어댑터 조건과 내 프로젝트의 재현 결과를 대조해 판단해야 합니다.

실무에서는 릴리스 문장을 그대로 운영 판단으로 옮기기보다, 경고 로그 수집, 코드 소유권 분리, 라우트별 404 테스트, 프리뷰 배포 검증을 순서대로 진행해야 합니다. canary 릴리스의 가치는 빠른 적용보다 빠른 확인에 있습니다. 현재 프로젝트가 어떤 캐시 API에 의존하는지, 어떤 라우트에서 not-found.tsx가 표시되는지, 빌드와 런타임 로그가 어떻게 달라지는지 확인해 두면 이후 stable 업그레이드 비용을 줄일 수 있습니다.

공식 기준과 확인 범위

확인일: 2026-09-12. API 설명은 Next.js 16 App Router 기준이며 과거 릴리스 글은 본문의 태그 범위를 유지합니다. 부분 API 코드는 기존 프로젝트에 통합하는 예시입니다.

• https://github.com/vercel/next.js/releases/tag/v16.3.0-canary.106
• https://github.com/vercel/next.js/pull/96448
• https://github.com/vercel/next.js/pull/96392