Next.js hostname을 넣었는데 왜 이미지가 막힐까? remotePatterns 다섯 칸 대조

CMS나 스토리지의 이미지 주소를 <Image>에 붙였는데 hostname is not configured under images가 뜨면, hostname 한 줄만 추가해서는 끝나지 않을 수 있다. Next.js는 실제 src와 remotePatterns의 protocol, hostname, port, pathname, search를 정확히 비교한다. 하위 도메인이나 경로 한 칸이 다르면 같은 회사의 이미지 서버라도 거부한다.

먼저 오류에 찍힌 실제 src를 그대로 복사한다. 그 주소와 next.config.js를 나란히 놓고 다섯 칸을 맞춘다. 이 순서를 따르면 무작정 **를 넓히거나 unoptimized로 우회하지 않고, 필요한 이미지 경로만 열 수 있다.

Tap to zoom

hostname만 보지 말고 URL 다섯 칸을 맞춘다

예를 들어 실제 주소가 다음과 같다고 가정한다.

https://cdn.example.com/products/42/cover.jpg?v=3

오류 이름에는 hostname이 보이지만, Next.js 공식 오류 문서는 아래 요소가 모두 정확히 맞아야 한다고 설명한다.

특히 example.com과 cdn.example.com은 다른 hostname이다. pathname: '/products/**'는 products 아래 경로를 받지만 '/products/'는 같은 뜻이 아니다. 오류 문구보다 실제 src를 기준으로 비교해야 한다.

필요한 경로만 remotePatterns에 연다

실제 이미지가 https://cdn.example.com/products/ 아래에 있고 검색 파라미터는 여러 값이 올 수 있다면 설정을 다음처럼 좁힐 수 있다.

// next.config.js
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'cdn.example.com',
        port: '',
        pathname: '/products/**',
      },
    ],
  },
}

export default nextConfig

객체에서 search를 생략하면 여러 검색 파라미터를 받을 수 있다. 특정 버전만 허용하려면 search: '?v=3'처럼 정확히 적는다. new URL('https://cdn.example.com/products/**') 형태는 Next.js 15.3.0부터 지원된다. 더 오래된 프로젝트라면 객체 형태를 쓰는 편이 버전 혼동을 줄인다.

Next.js의 remotePatterns 공식 문서는 허용 패턴을 가능한 구체적으로 잡으라고 안내한다. protocol, 경로, 검색 조건을 넓게 생략하면 의도하지 않은 URL까지 이미지 최적화 대상이 될 수 있다. 작동하는 가장 좁은 경로가 완료 기준이다.

더 넓은 이미지 장애부터 분리해야 한다면 Next.js 이미지가 안 보일 때 Network에서 확인할 세 줄을 먼저 확인한다. 이번 문제는 원본 파일 404나 CSS가 아니라 외부 URL 허용 패턴에 초점을 둔다.

설정 뒤에는 서버와 두 URL을 다시 확인한다

next.config.js를 저장한 뒤에도 같은 오류가 보이면 개발 서버를 다시 시작한다. 설정 파일은 실행 중인 프로세스가 이미 읽은 상태일 수 있다.

# 실행 중인 개발 서버를 정상 종료한 뒤 다시 시작
npm run dev

그다음 아래 순서로 확인한다.

1. 원본 외부 URL을 브라우저에서 직접 열어 이미지가 응답하는지 본다.
2. 페이지를 다시 열고 Console에서 un-configured host 오류가 사라졌는지 본다.
3. Network에서 /_next/image?... 요청이 성공하는지 본다.
4. 카드 크기와 실제 비율이 맞는지 화면에서 확인한다.

Tap to zoom

원본 URL부터 실패하면 remotePatterns 문제가 아니다. CDN 권한, 만료된 서명 주소, 파일 경로를 먼저 고쳐야 한다. 원본은 성공하지만 /_next/image만 실패하면 실제 요청 URL과 설정을 다시 대조한다. 두 응답을 나누면 수정할 위치가 달라진다.

환경변수로 CDN 주소를 조립한다면 Next.js 환경변수를 공개 값과 서버 값으로 가르는 기준도 함께 확인한다. 로컬과 배포에서 hostname이 달라지는 경우 실제 배포 src가 설정에 들어 있는지 봐야 한다.

버전 차이와 다른 이미지 오류를 분리한다

images.domains는 hostname만 나열하는 예전 설정이다. Next.js 14부터는 protocol과 경로까지 제한할 수 있는 remotePatterns를 권장하며 domains는 deprecated다. 새 설정을 만들 때는 버전이 허용하는 remotePatterns 형식을 선택한다.

host 오류가 사라진 뒤 width나 height 관련 메시지가 남을 수 있다. 원격 URL은 빌드 시 이미지 크기를 알 수 없으므로 <Image>에 크기를 제공해야 한다.

<Image
  src="https://cdn.example.com/products/42/cover.jpg?v=3"
  alt="검은색 러닝화 옆면"
  width={1200}
  height={800}
/>

fill을 쓰는 경우에는 부모의 위치와 크기 조건을 별도로 맞춘다. 이것은 host 허용과 다른 문제다. 오류를 한 번에 모두 고치려 하지 말고 host 허용, 원본 응답, 최적화 응답, 화면 크기 순서로 나눈다.

오늘은 실패한 이미지 주소 하나만 복사해 다섯 칸 표를 채운다. 가장 좁은 remotePatterns를 적용하고 서버를 다시 켠 뒤 원본과 /_next/image 응답이 모두 성공하면 작업을 끝낸다.

참고 출처

• next/image Un-configured Host (Next.js)
• Image Component와 remotePatterns (Next.js)

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.