Next.js Image remotePatterns 오류 해결: 외부 이미지 도메인 허용하기

학습 목표·선수 지식: 이미지 허용 실패와 원본 요청 실패를 구분합니다. 선수 지식: URL·HTTP 상태.

오류가 나는 URL부터 확인하기

대표 증상은 외부 이미지가 표시되지 않고 next/image의 un-configured host 오류가 나타나는 경우입니다. 먼저 브라우저 개발자 도구나 API 응답에서 최종 src 값을 확인합니다. CMS나 CDN을 거치는 동안 hostname이나 경로, query string이 예상과 달라질 수 있기 때문입니다.

예를 들어 코드에서는 images.example.com을 예상했지만 실제 URL이 cdn.example.com이거나, 경로가 /products/가 아니라 /uploads/라면 기존 패턴으로는 허용되지 않습니다.

remotePatterns가 URL을 검사하는 기준

remotePatterns는 외부 이미지 URL의 범위를 제한하는 설정입니다. 도메인 전체를 무조건 허용하기보다 실제 사용하는 protocol, hostname, port, pathname을 좁혀 설정할 수 있어 보안과 비용 측면에서 더 안전합니다.

특히 query string을 사용하는 CDN이라면 search 조건을 주의해야 합니다. query string을 허용할 필요가 없다면 빈 값으로 제한할 수 있고, 다양한 query string이 필요하다면 해당 키를 생략하는 방식으로 범위를 정합니다.

외부 이미지가 허용되지 않을 때 비교할 항목

항목	예시	확인 사항
protocol	https	실제 URL이 http인지 https인지 확인
hostname	images.example.com	cdn.example.com은 별도 호스트
port	빈 문자열	기본 포트와 별도 지정 포트를 구분
pathname	/products/**	/uploads/ 경로는 이 패턴에 포함되지 않음
search	생략 또는 빈 문자열	생략은 임의 쿼리 허용, 빈 문자열은 쿼리 없음만 허용

new URL('https://images.example.com/products/**')처럼 URL 객체를 쓰면 쿼리가 없는 URL의 search는 빈 문자열이 됩니다. 따라서 ?v=1 같은 쿼리가 붙은 이미지는 허용되지 않습니다. 아래 객체 예제는 search를 생략해 쿼리를 허용합니다. 특정 쿼리만 허용하려면 search: '?v=1'처럼 전체 문자열을 지정합니다. URL 객체 형식의 remotePatterns는 Next.js 15.3.0 이상 기준입니다.

next.config에서 안전하게 허용하기

아래 예시는 https://images.example.com/products/... 경로만 허용하는 기본 형태입니다.

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "images.example.com",
        port: "",
        pathname: "/products/**",
      },
    ],
  },
};

module.exports = nextConfig;

설정 파일 형식: 위 코드는 CommonJS 방식의 next.config.js 예제입니다. next.config.mjs나 next.config.ts를 사용한다면 마지막 줄은 export default nextConfig로 작성하고 기존 프로젝트의 모듈 형식을 따릅니다.

서브도메인이 여러 개라면 와일드카드를 사용할 수 있지만, 실제 필요한 범위보다 넓게 열지 않는 편이 좋습니다. 이미지가 저장되는 호스트와 경로를 확인한 뒤 필요한 패턴만 추가합니다.

next.config.js나 next.config.ts를 수정한 뒤에는 개발 서버를 다시 시작해야 합니다. 설정 파일 변경은 브라우저 새로고침만으로 반영되지 않을 수 있습니다.

수정 후 확인할 항목

• 실패한 이미지의 최종 URL이 허용한 protocol·hostname·pathname과 일치하는지 확인합니다.
• query string이 붙는 CDN이라면 search 조건 때문에 차단되지 않는지 확인합니다.
• 설정 변경 후 개발 서버를 재시작합니다. 배포 환경은 다시 빌드·배포한 뒤 실제 페이지를 열어 이미지 최적화 요청이 성공하고 이미지가 표시되는지 확인합니다. 빌드 성공만으로 모든 원격 이미지 요청을 검증한 것은 아닙니다.
• 원격 이미지에 width와 height를 주거나, fill을 사용할 때 적절한 sizes를 지정합니다.
• 이미지 서버 자체가 403·404를 반환하거나 인증을 요구하는 문제는 remotePatterns와 별도로 확인합니다.

실패를 URL 허용과 원본 전송으로 나눕니다

관찰	가능 원인	검사
최적화 URL 400	remotePatterns·width·quality 허용 불일치	실제 src·w·q와 images 설정
원본 URL도 403	인증 또는 원본 차단	원본 서버 접근 정책
200인데 화면 왜곡	CSS 비율·fill 부모 높이	렌더 박스 크기와 sizes

Next.js 16의 images.qualities 허용 목록도 확인합니다. 기본 허용값 75와 다른 q를 직접 최적화 URL에 보내면 400이 날 수 있어 hostname만 넓히는 수정으로는 해결되지 않습니다. 필요 품질만 명시하고 원격 호스트를 무조건 **로 열지 않습니다. 본문 Image 최적화 정책은 OG 봇이 원본 이미지 URL을 가져갈 수 있는지와 별개입니다.

정리

Next.js Image remotePatterns 오류는 대부분 실제 이미지 URL과 허용 패턴의 불일치에서 시작합니다. hostname만 보고 설정하기보다 protocol, port, pathname, query string까지 같은 URL 구조로 비교한 뒤 필요한 범위만 허용하면 됩니다.

전체 이미지·SEO 설정 흐름은 Next.js SEO 완전 가이드와 함께 확인하면 좋습니다.

업로드 전 이미지 파일 준비

외부 이미지 허용 설정을 확인한 뒤, CMS나 CDN에 올릴 원본 파일의 용량을 줄이고 싶다면 BlogFlow 이미지 압축 도구를 사용할 수 있습니다. JPG·PNG·WebP를 브라우저에서 처리하며, 결과의 화질과 용량을 확인한 뒤 업로드하면 됩니다. 파일 압축은 remotePatterns의 URL 허용 오류나 CSS의 이미지 찌그러짐을 해결하지 않으므로, 설정과 표시 비율은 위 항목에 따라 따로 확인하세요.

관련 글

• Next.js SEO 체크리스트: metadata·초기 HTML·OG 이미지 점검
• Vercel 404 NOT_FOUND 오류 해결: Next.js 배포 후 라우팅과 rewrites 확인

공식 기준과 확인 범위

확인일: 2026-09-12. API 설명은 Next.js 16 App Router 기준이며 과거 릴리스 글은 본문의 태그 범위를 유지합니다. 부분 API 코드는 기존 프로젝트에 통합하는 예시입니다.

• https://nextjs.org/docs/app/api-reference/components/image

공식 자료 재확인: 2026-09-12. 이 글의 실행하지 않은 브라우저/배포 점검은 독자 확인 과제로 구분합니다.

공식 문서

• Next.js 외부 이미지 호스트 오류 공식 문서