Invalid src prop: hostname is not configured under images in your next.config.js

이 오류가 의미하는 것

Next.js의 next/image는 외부 이미지를 최적화하기 전에 허용된 원격 주소인지 확인합니다. Image의 src URL이 next.config.js의 images.remotePatterns와 정확히 맞지 않으면 다음과 같은 오류가 표시됩니다.

Invalid src prop (...) on `next/image`, hostname (...) is not configured under images in your `next.config.js`

호스트 이름만 같아도 충분하지 않을 수 있습니다. 프로토콜, 호스트, 포트, 경로, 검색 문자열이 설정과 다르면 일치하지 않습니다.

먼저 확인할 항목

1. 오류에 표시된 실제 src URL을 복사하고 토큰이나 개인정보가 있으면 가린 뒤 기록합니다.
2. URL을 protocol, hostname, port, pathname, search로 나눠 기록합니다.
3. next.config.js의 images.remotePatterns에 같은 값이 있는지 확인합니다.
4. www.example.com과 example.com, http와 https, /images/와 /images/**처럼 실제 값과 설정이 다른 부분을 비교합니다.

수정 방법

외부 이미지 호스트가 실제로 필요한 경우 URL 범위를 좁혀 remotePatterns에 등록합니다.

// next.config.jsmodule.exports = {  images: {    remotePatterns: [      {        protocol: 'https',        hostname: 'assets.example.com',        port: '',        pathname: '/account123/**',      },    ],  },};

검색 문자열까지 사용하는 URL이라면 search 값도 의도한 범위로 설정해야 합니다. 모든 검색 문자열을 허용해야 하는지 먼저 확인하고, 불필요하게 넓은 와일드카드나 전체 호스트 허용을 기본값으로 사용하지 마십시오.

설정 변경 후 개발 서버를 재시작하고, 프로덕션 next build에서도 같은 이미지 URL을 다시 확인합니다. Next.js 15.3.0 이상에서는 new URL() 형식도 사용할 수 있지만, 현재 프로젝트의 Next.js 버전이 지원하는 설정 형식을 먼저 확인해야 합니다.

수정 후 판정

• 대상 URL의 이미지가 next/image를 통해 정상 응답합니다.
• 다른 호스트나 경로의 이미지는 의도하지 않게 허용되지 않습니다.
• 개발 서버 재시작과 프로덕션 빌드 이후에도 같은 오류가 재현되지 않습니다.

주의

오류를 없애기 위해 원격 호스트 전체를 무제한 허용하거나 unoptimized를 무조건 적용하지 마십시오. 외부 이미지 서버를 추가할 때는 이미지 출처와 운영 비용, 캐시 범위를 먼저 확인하십시오.