Next.js 16 업그레이드 후 빌드 오류 없이 발생한 4가지 문제점
Next.js 16 업그레이드 후 빌드 통과에도 불구하고 리다이렉트 미작동, API 라우트 오류 등 예상치 못한 문제 발생
middleware.ts 파일이 proxy.ts로 변경되었으나, 오류 없이 작동 중단되어 문제 인지 지연
revalidateTag API의 단일 인자 사용이 비권장되면서 데이터 불일치 발생, strict 모드 미적용 시 런타임 오류로 이어짐
next lint 명령어 제거 및 CI 설정 미변경으로 코드 품질 관리 공백 발생
레이아웃 컴포넌트에서 params 동기 접근 시 Next.js 16에서 비동기 처리로 변경되어 오류 발생
Next.js 16의 미들웨어(Middleware) 변경점
Next.js 16 버전에서는 기존 middleware.ts 파일이 proxy.ts로 변경되었으며, export 함수명 또한 달라졌다. 이 변경은 코드 컴파일 단계에서 오류를 발생시키지 않아 개발자가 인지하기 어렵게 만든다.
이전 버전: `middleware.ts` 파일 내 `middleware` 함수 export
변경 후: `proxy.ts` 파일 내 `proxy` 함수 export
이로 인해 기존 미들웨어 로직이 실행되지 않는 문제가 발생하며, 자동화된 코드 변환 도구(Codemod)를 사용하지 않거나 일부 파일이 누락된 경우 수동 확인이 필수적이다. 특히, 엣지 런타임(Edge Runtime) 동작이 필요한 경우 해당 파일의 존재 여부를 반드시 확인해야 한다.
revalidateTag API의 변경과 데이터 불일치
Next.js 16에서 `revalidateTag` API는 단일 인자 사용이 비권장되며, SWR 기반의 새로운 시스템으로 변경되었다. 이전 버전에서는 단일 인자 사용 시에도 컴파일 오류가 발생하지 않아 데이터 불일치(Data Inconsistency) 문제가 발생할 수 있다.
이전: `revalidateTag('products')` (단일 인자)
변경 후: `revalidateTag('products', 'max')` 또는 `revalidateTag('products', { expire: 0 })` (두 번째 인자 필수)
이 문제는 TypeScript의 strict 모드를 활성화하면 컴파일 시점에 오류로 감지되지만, 그렇지 않은 경우 런타임에서 오래된 데이터(Stale Data)가 노출되는 심각한 문제를 야기한다. 코드 변환 도구(Codemod)가 이 부분을 놓칠 수 있으므로 수동 검토가 권장된다.
next lint 제거와 CI/CD 파이프라인 영향
Next.js 16 버전부터 `next lint` 명령어가 완전히 제거되었으며, `next.config.ts`의 관련 설정도 삭제되었다. 이로 인해 기존에 `next lint`를 CI/CD 파이프라인의 일부로 사용하던 경우, 빌드 및 배포 과정이 오류 없이 통과되는 문제가 발생한다.
변경점: `next lint` 명령어 삭제, `next.config.ts` 설정 제거
해결 방안: ESLint를 직접 실행하도록 CI 설정을 변경 (`eslint .` 명령 사용)
코드 변환 도구(Codemod)는 `eslint.config.mjs` 파일 생성 및 `package.json` 스크립트 업데이트를 지원하지만, CI 설정 파일은 별도로 관리되므로 수동 확인 및 수정이 반드시 필요하다. 이는 코드 품질 관리 공백으로 이어질 수 있다.
비동기 처리로 변경된 params 접근 방식
Next.js 16에서는 `params` 객체 접근 방식이 동기에서 비동기로 변경되었다. 이전 버전에서는 직접 접근이 가능했지만, 최신 버전에서는 Promise 형태로 반환되므로 `await` 키워드를 사용하여 값을 받아와야 한다.
이전 (Next.js 15): `const id = params.id`
변경 후 (Next.js 16): `const { id } = await params`
이 변경 사항은 레이아웃(Layout), 페이지(Page), 라우트 핸들러(Route Handler) 등에서 `params`, `searchParams`, `cookies()`, `headers()`, `draftMode()` 등을 사용할 때 모두 적용된다. 빌드 시에는 오류가 발생하지 않지만, 해당 라우트에 접근하는 첫 번째 요청 시점에 오류가 발생할 수 있어 주의가 필요하다. 코드 변환 도구(Codemod)가 모든 파일을 처리하지 못할 수 있으므로 전체 코드베이스에서 직접적인 params 접근을 검색하여 업데이트해야 한다.
