Next.js Image remotePatterns 오류에서 먼저 확인할 것
Next.js Image 오류 해결은 에러 문구만 보고 도메인을 대충 추가하는 작업이 아닙니다. 실제 이미지 URL의 protocol, hostname, port, pathname, search가 `next.config.js`의 `images.remotePatterns`와 정확히 맞는지 확인해야 합니다. 외부 이미지는 보안과 비용 문제 때문에 허용 목록 밖의 URL을 자동 최적화하지 않으므로, 문제의 URL 구조를 먼저 좁히는 것이 핵심입니다.
이미지 설정은 SEO, 레이아웃 안정성, 배포 환경과도 이어집니다. 전체 흐름은 Next.js SEO 완전 가이드에서 함께 확인할 수 있습니다.
이 글은 Next.js SEO 완전 가이드: App Router metadata부터 배포 확인까지의 세부 항목입니다. 전체 설정 흐름과 관련 오류 해결 순서는 대표 허브 글에서 함께 확인할 수 있습니다.
증상부터 정확히 보기
대표 증상은 외부 이미지가 보이지 않거나, 개발자 도구와 터미널에 `next/image`의 un-configured host 관련 오류가 표시되는 상황입니다. 같은 컴포넌트라도 로컬 개발 환경에서는 보이는 것처럼 보이다가 빌드, 배포, 실제 브라우저 요청 시점에 실패할 수 있습니다.
먼저 실패한 이미지의 최종 `src` 값을 확인합니다. CMS, API, CDN, 쿼리스트링 처리 과정에서 실제 요청 URL이 코드에서 예상한 값과 달라지는 경우가 많습니다. 단순히 도메인만 비교하지 말고 `https://`, 서브도메인, 경로, 쿼리스트링까지 같은 기준으로 봐야 합니다.
문제가 생기는 이유
Next.js Image는 외부 이미지를 최적화할 때 허용된 URL 패턴만 처리합니다. 공식 문서 기준으로 `remotePatterns`는 protocol, hostname, port, pathname, search를 기준으로 매칭되며, 맞지 않는 요청은 거부됩니다. 이는 의도하지 않은 외부 URL을 이미지 최적화 서버가 대신 가져오지 않도록 막는 안전장치입니다.
기존 `images.domains` 방식은 도메인 단위 허용에 가깝기 때문에 경로나 쿼리 조건을 세밀하게 제한하기 어렵습니다. 최신 설정에서는 가능한 한 `remotePatterns`를 구체적으로 작성해 실제 사용하는 CDN 버킷, 계정 경로, 이미지 폴더만 허용하는 편이 안전합니다.
코드와 설정에서 고치는 방법
가장 먼저 실제 이미지 URL을 하나 복사한 뒤, 그 URL을 기준으로 `next.config.js` 또는 `next.config.ts`의 `images.remotePatterns`를 작성합니다. 아래 예시는 `https://images.example.com/products/…` 경로의 이미지만 허용하는 최소 형태입니다.
/** @type {import('next').NextConfig} */
const nextConfig = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 'images.example.com',
port: '',
pathname: '/products/**',
search: '',
},
],
},
}
module.exports = nextConfig쿼리스트링을 허용해야 한다면 `search` 기준을 의도적으로 정해야 합니다. 특정 버전 값만 허용하려면 `search: ‘?v=1234’`처럼 정확히 쓰고, 어떤 쿼리든 허용해야 하는 구조라면 `search` 키를 생략합니다. 반대로 `search: ”`는 쿼리스트링이 없는 URL만 허용한다는 뜻이므로, CDN이 자동으로 `?width=…` 같은 값을 붙이는지 확인해야 합니다.
서브도메인이 여러 개라면 `hostname: ‘**.example.com’` 같은 와일드카드를 사용할 수 있습니다. 다만 너무 넓게 열면 의도하지 않은 URL까지 최적화 대상이 될 수 있으므로, 가능하면 이미지가 실제로 저장되는 호스트와 경로를 좁혀서 작성합니다.
수정 후 확인할 체크리스트
설정을 바꾼 뒤에는 개발 서버를 다시 시작하고, 빌드와 배포 환경에서도 같은 URL이 통과하는지 확인합니다. `next.config.js`는 실행 중인 개발 서버에 자동으로 항상 반영되는 파일이 아니므로, 저장만 하고 브라우저 새로고침만 하는 검증은 부족합니다.
또한 “에 원격 URL을 문자열로 전달할 때는 `width`와 `height`를 함께 제공하거나, 레이아웃 의도에 맞게 `fill`과 `sizes`를 설정해야 합니다. remotePatterns 오류를 고친 뒤에도 크기 정보, alt, 응답 상태, CDN 권한 문제가 남아 있으면 화면에서는 여전히 이미지 문제가 있는 것처럼 보일 수 있습니다.
정리
Next.js Image remotePatterns 오류는 실제 이미지 URL과 허용 패턴의 불일치에서 시작되는 경우가 많습니다. URL의 protocol, hostname, port, pathname, search를 분리해 확인하고, 필요한 범위만 `remotePatterns`로 허용한 뒤 개발 서버 재시작, 빌드, 배포 환경까지 확인하면 같은 유형의 문제를 빠르게 줄일 수 있습니다.
공식 기준은 `next/image` Un-configured Host, Image Component, images 설정, next.config.js 문서에서 확인했습니다.
“Next.js Image remotePatterns 오류 해결: 외부 이미지 도메인 허용하기”에 대한 4개의 생각