Next.js 16 Image priority deprecated 대응: preload 전환과 quality 설정

Next.js 16 Image priority deprecated quality 설정 문제는 두 가지 작업으로 해결한다. 첫째는 priority prop을 preload나 loading="eager", fetchPriority="high"로 바꾸는 작업이다. 둘째, 75가 아닌 quality 값을 쓴다면 그 값을 images.qualities에 등록한다.

images.qualities 기본값은 Next.js 16에서 모든 quality 허용([1..100])에서 [75]로 바뀌었다. 하위 호환을 깨는 변경이다. Next.js 15 이하에서 quality={90}처럼 쓰던 코드도 16에서는 설정을 추가하기 전까지 75로 제공된다. 이 글은 Next.js 16으로 업그레이드한 App Router 프로젝트의 next/image를 대상으로 하며, 문서 기준일은 2026-10-20이다.

목차

Next.js 16 Image 변경 범위와 근거 문서

priority가 deprecated됐다는 근거는 Next.js Image 컴포넌트 레퍼런스(image.mdx)의 priority 절이다. 원문은 "Starting with Next.js 16, the priority property has been deprecated in favor of the preload property in order to make the behavior clear."다. 동작을 명확히 하려고 이름을 바꿨다는 설명이 붙어 있다.

출처에 따라 다루는 범위가 다르다. Next.js 16 공식 발표글의 Deprecations 표에는 middleware.ts, next/legacy/image, images.domains, revalidateTag 단일 인자만 있고 priority는 없다. 업그레이드 가이드의 next/image 절에도 priority→preload 항목이 빠져 있다. 발표글이나 가이드만 읽으면 이 변경을 놓치기 쉽다.

항목 Next.js 16 변경 내용 근거
priority deprecated, 대체 prop은 preload image.mdx
images.qualities 기본값 [1..100] → [75], quality는 가장 가까운 허용 값으로 변환 발표글, 업그레이드 가이드
quality 허용 범위 1~100 정수, 기본값 75 image.mdx
직접 /_next/image 요청 지원하지 않는 q 값은 400 반환 업그레이드 가이드

image.mdx와 발표글 어디에도 priority가 실제로 제거되는 버전은 적혀 있지 않다. 현재는 deprecated 상태로만 기록되어 있다.

시작 전 준비: 런타임 요구사항과 업그레이드 명령

runtime-upgrade-checklist

Next.js 16은 런타임 최소 버전을 올렸다. Next.js 16 업그레이드 가이드의 ‘Node.js runtime and browser support’ 표 기준이다.

대상 최소 버전
Node.js 20.9.0 (LTS), Node.js 18 지원 종료
TypeScript 5.1.0
브라우저 Chrome 111+, Edge 111+, Firefox 111+, Safari 16.4+
Node.js 버전 확인 필수
로컬과 CI, 배포 환경 모두 `node -v`로 20.9.0 이상인지 확인한다. Node.js 18 이미지를 쓰는 배포 파이프라인이 있다면 업그레이드 전에 런타임부터 올려야 한다.
요구사항을 충족하면 발표글이 안내하는 명령으로 업그레이드한다.
# Use the automated upgrade CLI
npx @next/codemod@canary upgrade latest

# ...or upgrade manually
npm install next@latest react@latest react-dom@latest

# ...or start a new project
npx create-next-app@latest

업그레이드 가이드의 codemod 기능 목록에는 Image prop 변환 항목이 없다. codemod를 실행한 뒤에도 priority 교체와 quality 값 점검은 코드에서 직접 확인한다. 업그레이드 가이드에 계정이나 권한 관련 준비사항은 없고, 런타임 요구사항과 업그레이드 명령이 준비 단계의 전부다.

1단계: priority를 preload 또는 loading·fetchPriority로 바꾸기

priority-to-preload-swap

프로젝트 전체에서 priority를 검색하면 교체 대상이 나온다. 보통 LCP 요소나 히어로 이미지다.

image.mdx의 권장 사항은 명확하다. "In most cases, you should use loading="eager" or fetchPriority="high" instead of preload." priority를 preload로 기계적으로 바꾸기보다 먼저 loading="eager"나 fetchPriority="high"로 충분한지 판단한다.

// Next.js 16부터 deprecated
<Image priority />

// 대부분의 경우 권장되는 대체
<Image loading="eager" />
<Image fetchPriority="high" />

// <head>에 <link>를 삽입해 미리 로드
<Image preload={true} />

preload가 맞는 경우와 맞지 않는 경우

preload는 "A boolean that indicates if the image should be preloaded."로 정의되며 기본값은 false다. true로 두면 <head>에 <link>를 삽입해 이미지를 미리 로드한다.

<Image preload={false} />

image.mdx가 preload 사용을 안내하는 조건은 세 가지다.

  • 이미지가 LCP 요소인 경우
  • above the fold, 주로 히어로 영역에 있는 경우
  • <body>에서 이미지가 발견되기 전에 <head>에서 로드를 시작하고 싶을 때

반대로 다음 조건에서는 preload를 쓰지 않는다.

  • 뷰포트에 따라 LCP 후보 이미지가 여러 개다
  • 같은 이미지에 loading 속성을 쓰고 있다
  • fetchPriority 속성과 함께 쓰려는 상황이다

모바일과 데스크톱에서 다른 히어로 이미지를 보여주는 레이아웃은 첫 번째 조건에 해당한다. 이런 경우에는 fetchPriority="high" 쪽이 문서 권장과 맞는다. image.mdx에는 fetchPriority 전용 절이 따로 없고, preload 절의 언급이 유일한 근거다.

확인 방법: 교체 후 코드베이스를 다시 검색해 priority prop이 남아 있지 않은지 본다. preload를 쓴 컴포넌트에 loading이나 fetchPriority가 함께 붙어 있지 않은지도 점검한다.

2단계: images.qualities에 quality 값 등록하기

quality prop은 "An integer between 1 and 100 that sets the quality of the optimized image."이고 기본 quality는 75다.

<Image quality={75} />

컴포넌트에 75 외의 값이 있다면 그 값을 next.config의 images.qualities에 넣는다. 업그레이드 가이드의 TypeScript 예시는 다음과 같다.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  images: {
    qualities: [50, 75, 100],
  },
}

export default nextConfig

next.config.js를 쓰는 프로젝트라면 image.mdx의 예제 형식을 따른다.

module.exports = {
  images: {
    qualities: [25, 50, 75, 100],
  },
}

설정 값은 실제 쓰는 quality만 담는다. 코드에 quality={100}과 기본값만 있다면 [75, 100]이면 충분하다. 목록이 길수록 서버가 만들어 낼 수 있는 이미지 변형도 늘어난다.

qualities 제한을 푸는 위험
image.mdx는 이 필드가 Next.js 16부터 required인 이유로 “unrestricted access could allow malicious actors to optimize more qualities than you intended.”를 든다. 1부터 100까지 전부 허용하는 목록을 넣으면 이 보호가 사라진다. 컴포넌트에서 쓰는 값만 등록한다.
### 컴포넌트 값 정리

설정을 넣은 뒤에는 컴포넌트 쪽 quality prop이 허용 목록에 있는지 하나씩 맞춘다. 목록 밖의 값은 오류 없이 가장 가까운 허용 값으로 강제 변환되고, 맞추지 않았을 때의 결과는 의도와 다른 화질이다. [50, 75, 100] 설정에서 quality={100}은 그대로 쓰이지만 quality={90} 같은 값은 목록에 추가하거나 100으로 바꿔야 의도가 분명해진다.

확인 방법: quality= 검색 결과의 숫자 집합과 images.qualities 배열이 일치하는지 비교한다.

결과 확인: 개발 로그, /_next/image 응답, 마이그레이션 체크리스트

빌드 통과만으로는 불충분
빌드가 통과했다고 끝난 것은 아니다. 업그레이드 가이드의 체크리스트는 “A green build alone does not close runtime findings.”라고 명시한다.
확인은 세 갈래로 진행한다.

개발 모드 경고 로그

next dev로 이미지를 쓰는 페이지를 연다. image.mdx 예시는 qualities: [50, 75, 100]에서 quality가 80이면 75로 제공되며, "Development logs a warning so you can add the value to the allowlist."라고 설명한다. 터미널에 이 경고가 찍히면 해당 값을 images.qualities에 추가하거나 prop 값을 목록 안으로 바꾼다. 주요 페이지를 모두 열었는데 경고가 없다면 쓰는 값이 목록 안에 있다고 판단한다.

직접 /_next/image 요청

컴포넌트 prop은 가까운 값으로 변환되지만, /_next/image 엔드포인트를 직접 호출하는 경우는 다르게 처리된다. 업그레이드 가이드는 "test direct /_next/image requests because unsupported q values return 400."이라고 안내한다. 외부 서비스나 CDN 설정, 이메일 템플릿처럼 이미지 URL을 직접 조립하는 곳이 있다면 그 URL의 q 값으로 요청을 보내 400이 아닌 응답이 오는지 확인한다.

호출 경로 허용 목록 밖 quality의 결과
<Image quality={...} /> 가장 가까운 허용 값으로 변환, 개발 환경에서 경고
직접 /_next/image?q=... 요청 400 반환

공식 체크리스트 대조

업그레이드 가이드 ‘Review migration checklist’에서 이미지와 관련된 항목은 세 가지다.

  • "The app meets the Node.js, TypeScript, and React requirements in this guide."
  • "Affected image requests succeed under the documented restrictions and defaults while preserving the intended quality."
  • "The app’s supported checks and affected runtime behavior pass."

두 번째 항목은 요청 성공과 의도한 quality 유지를 동시에 요구한다. 400이 없다는 사실만으로는 부족하고, 변환 없이 원래 의도한 값으로 제공되는지까지 봐야 한다.

함께 바뀐 next/image 기본값과 주의사항

priority와 quality만 고치면 다른 변경을 놓친다. 업그레이드 가이드와 발표글의 Behavior Changes 표에는 next/image 기본값 변경이 더 있다.

images.minimumCacheTTL 기본값은 60초에서 4시간(14400초)으로 늘었다. 원본 이미지가 자주 바뀌어 이전 캐시 동작이 필요하면 값을 명시한다.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  images: {
    minimumCacheTTL: 60,
  },
}

export default nextConfig

기본 images.imageSizes 배열에서는 16이 빠졌다. 발표글은 이 값이 "used by only 4.2% of projects"였다고 밝힌다. 16px 크기에 의존하는 아이콘성 이미지가 있다면 imageSizes를 직접 지정해야 한다.

images.maximumRedirects는 무제한에서 최대 3회로 바뀌었다. 리다이렉트를 여러 번 거치는 원격 이미지 URL은 이 제한에 걸린다. 쿼리 문자열이 붙은 로컬 이미지는 images.localPatterns.search 설정이 있어야 한다.

로컬 IP 최적화 차단
Next.js 16은 로컬 IP 이미지 최적화를 기본으로 차단한다. `dangerouslyAllowLocalIP`로 다시 열 수 있지만 업그레이드 가이드는 “Only enable once you understand the SSRF risk.”라고 경고한다. 내부망 이미지 서버가 꼭 필요한 경우가 아니라면 기본 차단을 유지한다.
deprecated 목록에는 `next/legacy/image`와 `images.domains`도 있다. 대체 경로는 각각 `next/image`, `images.remotePatterns`다. `priority`를 정리하는 김에 이 두 항목도 함께 옮기면 이미지 관련 경고를 한 번에 정리하게 된다.

자주 묻는 질문

priority를 그대로 두면 Next.js 16에서 바로 깨지나?

image.mdx는 Next.js 16부터 priority가 deprecated라고만 기록한다. 실제 제거 버전은 image.mdx와 발표글 모두에 적혀 있지 않다. 대체 prop이 정해져 있으므로 업그레이드 시점에 교체해 두는 편이 안전하다.

priority를 preload로 일괄 치환해도 되나?

문서는 대부분의 경우 loading="eager"나 fetchPriority="high"를 권장한다. 뷰포트별 LCP 후보가 여러 개이거나 loading, fetchPriority를 함께 쓰는 이미지에는 preload를 쓰지 말라고 명시한다. 일괄 치환보다 이미지별 조건을 보고 고른다.

quality={80}을 썼는데 화질이 달라 보인다. 원인은?

images.qualities가 기본값 [75]이거나 80이 없는 목록이면 가장 가까운 허용 값으로 변환된다. [50, 75, 100] 설정에서 80은 75로 제공된다. 80을 images.qualities에 추가하면 의도한 값이 적용된다.

직접 만든 이미지 URL이 400을 반환한다.

/_next/image에 지원하지 않는 q 값을 보내면 400이 반환된다. 그 q 값을 images.qualities에 등록하거나 URL의 값을 허용 목록 안으로 바꾼다.

이후 점검할 Next.js 16 이미지 설정

priority 교체와 images.qualities 등록이 끝나면 이미지 쪽 업그레이드 작업의 대부분이 정리된다. 남은 부분은 원격 이미지 설정이다. images.domains를 images.remotePatterns로 옮기는 작업과 maximumRedirects 3회 제한에 걸리는 외부 URL 점검이 이어지는 주제다.

캐시 정책도 따로 다룰 만하다. minimumCacheTTL 14400 기본값이 CDN 캐시와 어떻게 겹치는지, next/legacy/image deprecated 상태의 레거시 컴포넌트를 next/image로 옮길 때의 변경점, 그리고 Next.js 16 업그레이드 codemod가 처리하는 범위와 수동으로 고칠 항목의 구분이 다음 점검 대상이다.

이 글 공유하기