Invalid src prop, next/image, remotePatterns | 외부 이미지가 깨지면 설정은 어디인가?
넥스트 이미지가 Invalid src를 내면 외부 주소 호스트가 remotePatterns에 없는 상태다. next.config.js의 images 칸에 프로토콜·호스트·경로를 맞추고 개발 서버를 다시 켠다. unoptimized는 최적화만 끈다. Next.js, 이미지 최적화, 카카오 CDN, 슈퍼베이스 스토리지, 버셀, 프론트엔드, 개발자 기준. 2026년 9월 Next.js 공식 문서.
Invalid src는 넥스트 이미지에 넣은 외부 주소의 호스트가 설정 파일의 원격 패턴에 없어서, 최적화 경로가 그 주소를 거절한 줄입니다. 파일 경로가 틀린 게 아니라, 허용 목록이 그 주소와 한 칸이라도 안 맞을 때 납니다.
카카오 프로필이나 스토리지처럼 외부 주소로 썸네일을 붙이면, 로컬 미리보기는 되고 빌드만 빨간 줄이 뜹니다. 제가 돌리는 사이트도 다음 검색 이미지 주소를 그대로 넣었다가 같은 줄을 봤죠.
허용할 호스트를 원격 패턴에 적고 개발 서버를 다시 켜세요. 최적화 끄기는 허용 목록을 대신하지 않습니다. 근거는 넥스트 미설정 호스트와 이미지 컴포넌트 문서입니다.
Invalid src는 허용 목록이 그 호스트를 안 연 줄이다
외부 주소를 최적화하려면 설정에 그 호스트가 있어야 합니다.
넥스트 이미지는 기본 로더가 /_next/image로 원본을 대신 엽니다. 서버가 임의 주소를 열면 안 되니, 설정에 적어 둔 패턴만 통과시킵니다. 공식 미설정 호스트 문서는 이 줄을, 주소에 있는 호스트가 images.remotePatterns에 없을 때 난다고 적습니다. 매칭은 대소문자까지 같고, 한 칸만 달라도 실패합니다.
콘솔에 자주 보이는 문장은 Invalid src prop 뒤에 거절된 주소, 그리고 그 호스트가 설정에 없다는 설명입니다. 개발 모드에서는 렌더 시점에 바로 던지고, 배포 뒤에는 최적화 주소가 400으로 죽기도 합니다. 화면만 깨지고 빌드는 통과한 것처럼 보이면, 네트워크 탭에서 /_next/image?url= 응답을 보세요.
사용자 입력 URL을 서버가 대신 여는 자리는 보안 글입니다. 그 칸은 링크 미리보기와 넥스트 이미지에서 다룹니다. 여기서는 내가 정한 씨디엔·스토리지 호스트가 설정에 없는 칸만 봅니다.
먼저 기억할 것 | Invalid src는 파일이 없다는 뜻이 아닙니다. 최적화 경로가 그 호스트를 열 권한이 없다는 뜻입니다. public 아래 상대 경로와 https 주소를 한 에러로 묶지 마세요.
외부 주소는 설정에 호스트가 있어야 최적화 경로를 탄다
설정은 어디를 열면 되나
프로젝트 루트의 넥스트 설정에서 images 칸을 엽니다.
파일 이름은 next.config.js 또는 next.config.mjs입니다. 앱 라우터든 페이지 라우터든 같은 칸입니다. 넥스트 15.3부터는 주소 객체 배열도 받습니다. 그 전에는 프로토콜·호스트·포트·경로를 객체로 적었습니다. 14에서 옛 images.domains는 폐기 경고입니다. 호스트만 적고 경로를 못 좁히니, 지금 신규는 원격 패턴만 쓰세요.
한국에서 1인으로 넥스트를 붙이면, 카카오 로그인 프로필과 슈퍼베이스 스토리지가 첫 외부 주소인 경우가 많습니다. 두 호스트를 한 번에 넣지 말고, 실제로 깨진 src를 복사해 한 줄씩 넣으세요. 설정만 저장하고 개발 서버를 안 끄면 이전 목록이 남습니다.
공식 문서는 예시 주소 https://example.org/images/example?v=1234를 프로토콜, 호스트, 포트, 경로, 쿼리 다섯 칸으로 나눕니다. http와 https는 다릅니다. example.org와 www.example.org와 assets.example.org도 다릅니다. 로컬에서 포트를 붙인 주소는 포트 칸이 비어 있으면 떨어집니다. 경로를 /images/만 적으면 그 아래 파일은 통과하지 못하고, /images/**처럼 끝 와일드카드가 필요합니다.
쿼리 칸은 더 잘 속습니다. 객체에서 search: ''를 적거나, 주소 생성자로 패턴을 만들면 검색 문자열이 빈 값으로 고정됩니다. 빈 값은 쿼리가 없는 주소만 허용한다는 뜻입니다. 썸네일 URL에 ?v=나 만료 토큰이 붙으면 호스트는 맞는데도 같은 Invalid src가 납니다. 쿼리를 허용하려면 객체에서 search 키를 빼세요.
깨진 src
설정이 어긋난 칸
고칠 곳
https인데 설정은 http
프로토콜
https로 맞추기
cdn.example.com, 설정은 example.com
호스트
서브도메인 또는 **.example.com
localhost:3000 미리보기
포트
포트 칸에 3000
/thumbs/a.jpg, 설정은 /thumbs/
경로
/thumbs/**
?v=123 이 붙은 주소
쿼리
search 키를 빼기
와일드카드는 경로와 호스트 앞에만 의미가 있습니다. *는 한 칸, **는 앞쪽 서브도메인 여러 칸 또는 경로 끝입니다. 가운데에 넣으면 문서대로 동작하지 않습니다. 프로토콜을 생략하면 모든 프로토콜이 열린 것과 같으니, 한국 배포에서는 https만 적는 쪽이 안전합니다.
주소 생성자는 쿼리를 기본으로 막는다
// 넥스트 15.3+
// new URL에 쿼리를 안 적으면 search가 '' 가 되어
// ?v= 가 붙은 src는 거절된다
module.exports = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: '**.kakaocdn.net',
pathname: '/**',
// search 키를 빼야 쿼리 허용
},
],
},
}
함정 | 호스트만 맞추고 쿼리를 빈 문자열로 두면, 캐시 버스팅이 붙은 썸네일은 계속 거절됩니다. 콘솔의 거절 주소 전체를 설정과 나란히 보세요.
거절된 주소를 다섯 칸으로 나눠 보면 어느 칸이 빠졌는지 바로 보인다
최적화 끄기와 원격 패턴은 다른 칸이다
최적화 끄기는 허용 목록 대체가 아닙니다. 외부 주소를 쓰려면 패턴을 적으세요.
넥스트 이미지 문서는 unoptimized를 원본을 그대로 내보내는 속성으로 적습니다. 품질, 크기, 포맷을 바꾸지 않습니다. 작은 그림, 벡터, 움직이는 그림처럼 최적화가 이득이 없을 때 쓰라고 합니다. 설정 파일에 images.unoptimized: true를 넣으면 사이트 전체가 원본으로 나갑니다. 정적보내기처럼 최적화 API가 없는 배포에서 쓰는 스위치입니다.
컴포넌트에 최적화 끄기를 주면 그 장은 /_next/image를 안 탑니다. 기본 로더의 호스트 검사가 빠질 수 있어, 빨간 줄이 잠시 사라집니다. 그건 허용 목록을 연 게 아닙니다. 브라우저가 원본 주소를 직접 열 뿐입니다. 원본 서버가 한국 아이피나 버셀 함수 아이피를 막으면, 설정 에러는 없어지고 그림만 깨집니다. 교차 출처 헤더 문제는 프리플라이트와 허용 출처와 자리가 다릅니다.
칸
하는 일
Invalid src와의 관계
원격 패턴
최적화 API가 열 외부 주소를 허용
없으면 거절
컴포넌트 최적화 끄기
그 장만 원본 src
호스트 검사를 우회할 수 있음
전역 최적화 끄기
사이트 전체 원본
최적화 API 자체를 끔
옛 domains
호스트만 허용, 경로 없음
폐기. 신규 금지
인증이 필요한 원본은 기본 로더가 헤더를 전달하지 않습니다. 공식 문서는 그런 장에 최적화 끄기를 검토하라고 적습니다. 공개 씨디엔 썸네일을 최적화하고 싶으면 원격 패턴이 본 설정입니다.
최적화 끄기는 한 장만, 허용은 설정 파일에서
import Image from 'next/image'
// 공개 씨디엔: 원격 패턴에 호스트를 넣고 최적화를 탄다
<Image src="https://t1.kakaocdn.net/thumb.png" width={400} height={400} alt="프로필" />
// SVG처럼 최적화가 이득이 없는 장
<Image src="/icon.svg" width={32} height={32} alt="" unoptimized />
public 경로와 https 주소를 한 설정에 넣지 마라
public 아래 경로는 로컬 패턴, https 주소는 원격 패턴입니다.
src="/images/posts/3715/img-1.jpg"처럼 슬래시로 시작하는 값은 사이트 안의 파일입니다. 원격 패턴이 필요 없습니다. 정적보내기로 가져온 파일은 빌드가 크기를 압니다. 외부 주소는 빌드가 파일을 못 보니 너비와 높이를 직접 적어야 합니다. 비율을 모르면 fill과 부모의 위치 지정을 씁니다.
넥스트 14.2.15부터는 로컬 패턴으로 public 아래 경로도 좁힐 수 있습니다. /assets/images/**만 열어 두면, 다른 로컬 경로는 400입니다. 로컬 패턴을 켠 뒤에 검색 파라미터를 빈 문자열로 두면, ?t=가 붙은 로컬 주소도 거절됩니다. 미설정 로컬 패턴 문서가 그 줄을 따로 설명합니다.
하이드레이션 빨간 줄과 섞지 마세요. 서버 HTML과 브라우저 첫 그림이 다른 칸은 하이드레이션 미스매치입니다. 여기는 주소 허용입니다. 최적화된 응답의 캐시 헤더는 캐시 컨트롤에서 다룹니다.
섞지 말 것 | 원격 패턴에 /images/** 를 넣어도 public 폴더는 열리지 않습니다. 로컬은 슬래시 경로, 외부는 https 주소입니다.
슬래시 경로는 public, https 주소는 원격 패턴이다
카카오 씨디엔과 슈퍼베이스는 src에서 복사한다
프로필과 스토리지 도메인을 실제 src에서 복사해 넣으세요.
카카오 로그인 프로필은 시기에 따라 호스트가 갈립니다. t1.kakaocdn.net 한 줄만 넣고 k.kakaocdn.net이 오면 같은 에러가 납니다. 슈퍼베이스 스토리지는 프로젝트 아이디가 호스트에 들어갑니다. 프로젝트.supabase.co와 스토리지 전용 호스트를 헷갈리면, 대시보드 URL과 화면 src가 서로 다릅니다. 와일드카드로 한 번에 열기 전에, 거절된 주소의 호스트를 그대로 한 줄 넣는 쪽이 빠릅니다.
리다이렉트가 있으면 패턴을 한 번 더 보세요. 기본 로더는 원격 그림을 열 때 리다이렉트를 따라가고, 도착 주소는 패턴을 다시 검사하지 않습니다. 공식 문서는 최대 리다이렉트 횟수로 줄이거나 끌 수 있다고 적습니다. 짧은 주소가 다른 버킷으로 넘어가는 썸네일이면, 첫 호스트만 허용해도 최적화 서버는 도착지를 엽니다. 내가 정한 씨디엔이 아니라 사용자 주소를 서버가 따라가는 구성이면, 다시 링크 미리보기 칸입니다.
[ ] 콘솔에 찍힌 거절 주소 전체를 복사했다
[ ] 프로토콜, 호스트, 포트, 경로, 쿼리를 설정과 나란히 봤다
[ ] 원격 패턴에 그 호스트를 넣었다
[ ] search 빈 문자열이 쿼리를 막는지 확인했다
[ ] 개발 서버를 끄고 다시 켰다
[ ] 배포 뒤에는 /_next/image 응답이 200인지 봤다
모듈을 못 찾는 줄과 이 줄을 한 로그에 섞지 마세요. 설치 위치 문제는 모듈을 찾을 수 없음입니다. 여기는 이미지 주소 허용입니다.
