Next.js 이미지 안 보임, Network에서 확인할 세 줄

AI 코딩 도구가 만든 Next.js 화면에서 글자와 버튼은 보이는데 이미지만 깨질 때가 있습니다. 초보자는 바로 "컴포넌트를 다시 만들어야 하나"라고 생각하기 쉽지만, 실제로는 이미지 요청 한 줄, 파일 위치 하나, 또는 next/image 설정 하나에서 멈춘 경우가 많습니다. 먼저 이미지를 다시 만들지 말고 Network에서 Request URL, Status Code, Content-Type 세 줄을 확인해야 합니다. 이 세 줄이 브라우저가 실제로 부른 주소와 받은 결과를 보여 줍니다.

Tap to zoom

nextjs.org의 public 폴더 문서는 public 폴더의 파일이 사이트 루트에서 제공된다고 설명합니다. 즉 public/profile.png는 /profile.png로 불러야 합니다. 또 nextjs.org의 Image 컴포넌트 문서는 src, alt, width, height 같은 값을 명확히 받아야 한다고 설명합니다. 원격 이미지는 더 엄격합니다. nextjs.org의 next-image-unconfigured-host 문서는 원격 이미지 URL이 remotePatterns의 프로토콜, 호스트, 경로와 정확히 맞아야 한다고 안내합니다. 그래서 이 글의 목표는 하나입니다. 3분 안에 경로 문제인지, 컴포넌트 문제인지, 원격 이미지 설정 문제인지 좁히는 것입니다.

30초 안에 브라우저가 부른 이미지 주소를 봅니다

먼저 개발자 도구의 Network 탭을 열고 Img 또는 이미지 요청만 필터링합니다. 화면에 깨진 이미지 아이콘이 있다면 새로고침한 뒤 실패한 이미지 요청을 클릭합니다. 여기서 봐야 할 값은 세 줄입니다.

Request URL:
Status Code:
Content-Type:

Status Code가 404라면 이미지 파일을 찾지 못한 것입니다. Content-Type이 text/html이라면 이미지가 아니라 페이지 HTML이 돌아왔을 가능성이 있습니다. 이 경우 화면 코드를 고치기 전에 src가 실제 파일로 연결되는지 봐야 합니다.

AI에게도 이 세 줄을 먼저 붙여야 합니다. "이미지가 안 보여요"라고만 쓰면 AI는 CSS, 컴포넌트, 설정을 한꺼번에 바꾸려고 할 수 있습니다. 반대로 요청 URL과 상태 코드를 주면 수정 범위가 이미지 경로 또는 설정 파일로 좁아집니다.

1분째에는 public 폴더와 src 경로를 맞춥니다

초보가 가장 자주 헷갈리는 지점은 public을 URL에 그대로 쓰는 것입니다. Next.js에서 public/logo.png 파일을 보여주려면 보통 이렇게 씁니다.

<img src="/logo.png" alt="서비스 로고" />

아래처럼 쓰면 파일 구조를 URL로 착각한 것입니다.

<img src="/public/logo.png" alt="서비스 로고" />

확인 순서는 간단합니다.

파일 위치: public/logo.png
브라우저 주소: http://localhost:3000/logo.png
컴포넌트 src: /logo.png

파일이 public/images/logo.png에 있으면 src는 /images/logo.png가 됩니다. 여기서 중요한 기준은 public이라는 폴더명은 주소에 쓰지 않는 것입니다. 이 규칙 하나만 맞춰도 AI가 만든 랜딩 페이지의 깨진 로고, 히어로 이미지, 아이콘 문제가 바로 줄어듭니다.

2분째에는 파일명 대소문자와 확장자를 그대로 봅니다

로컬 Windows 환경에서는 대소문자 실수가 늦게 드러날 수 있습니다. 예를 들어 파일은 Hero.PNG인데 코드가 /hero.png를 부르면 배포 환경에서만 404가 날 수 있습니다. 파일명과 코드의 철자를 눈으로 맞춰야 합니다.

파일명: product-card.webp
코드: /images/product-card.webp
확인: 대소문자, 하이픈, 확장자까지 같은가

특히 AI가 이미지를 만들거나 옮긴 뒤에는 hero.png, Hero.png, hero-1.png처럼 비슷한 파일명이 여러 개 생길 수 있습니다. 이때는 파일 탐색기에서 이름을 복사해 코드의 src에 붙이는 방식이 가장 빠릅니다.

초보 단계에서는 이미지 경로를 변수로 조합하기보다 먼저 고정 문자열로 확인하는 편이 좋습니다.

// 먼저 이렇게 확인합니다.
<img src="/images/product-card.webp" alt="상품 카드 예시" />

고정 경로로 보이면 그 다음에만 배열, CMS 데이터, 환경변수로 옮깁니다. 이미지가 안 보이는 상태에서 동적 경로부터 고치면 원인이 더 흐려집니다.

next/image를 쓴다면 width, height, alt를 먼저 채웁니다

next/image를 쓰면 브라우저 기본 <img>보다 더 많은 도움을 받지만, 그만큼 필요한 값도 있습니다. 가장 단순한 로컬 이미지는 다음처럼 시작합니다.

import Image from "next/image";

export default function Page() {
  return (
    <Image
      src="/images/product-card.webp"
      alt="상품 카드 예시"
      width={800}
      height={450}
    />
  );
}

width와 height가 빠졌거나 숫자가 너무 이상하면 레이아웃이 무너지거나 빌드 과정에서 오류가 날 수 있습니다. alt도 비워두지 않는 편이 좋습니다. developer.mozilla.org의 img 문서도 alt가 이미지 대체 텍스트로 쓰인다는 점을 설명합니다.

이미지가 아예 안 보인다면 CSS도 확인해야 합니다. 부모 요소에 height: 0, overflow: hidden, opacity: 0, display: none이 들어갔는지 봅니다. 다만 첫 순서는 CSS가 아닙니다. 요청 URL이 200으로 이미지 파일을 가져오는지가 먼저입니다. 요청이 실패하면 CSS를 고쳐도 화면에는 이미지가 나오지 않습니다.

원격 이미지는 remotePatterns가 URL과 정확히 맞아야 합니다

외부 URL 이미지를 next/image로 불러올 때는 next.config.js의 images.remotePatterns를 확인해야 합니다. Next.js 오류 문서는 프로토콜, 호스트명, 포트, 경로, 검색 문자열이 설정과 정확히 맞아야 한다고 설명합니다.

Tap to zoom

예를 들어 이미지 주소가 아래와 같다고 하겠습니다.

https://cdn.example.com/products/card.webp

설정은 이런 모양으로 시작할 수 있습니다.

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

export default nextConfig;

여기서 http와 https는 다릅니다. cdn.example.com과 images.example.com도 다릅니다. /products/**와 /assets/**도 다릅니다. 원격 이미지를 고칠 때는 이미지 URL을 쪼개서 설정과 한 칸씩 비교해야 합니다.

AI에게 물어볼 때도 실제 비공개 서명 URL이나 토큰을 그대로 붙이지 마세요. 필요한 것은 전체 비밀값이 아니라 구조입니다.

원격 이미지가 next/image에서 막힙니다.

이미지 URL 구조:
https://cdn.example.com/products/card.webp

현재 next.config.js images 설정:
[remotePatterns 부분만 붙여넣기]

요청:
1. protocol, hostname, pathname이 맞는지 먼저 비교해 주세요.
2. 전체 설정을 갈아엎지 말고 remotePatterns 최소 수정만 제안해 주세요.
3. 보안 토큰이나 서명 URL을 코드에 하드코딩하지 않는 방식으로 설명해 주세요.

배포 후에만 깨지면 새 이미지가 서버에 반영됐는지 확인합니다

로컬에서는 보이는데 배포 후에만 이미지가 깨질 수 있습니다. 이때는 세 가지를 봅니다.

특히 정적 파일은 "파일을 폴더에 넣었다"와 "실제 서비스가 그 파일을 서빙한다"가 다를 수 있습니다. 배포 후에는 이미지 주소를 브라우저 주소창에 직접 넣어 봅니다.

https://example.com/images/product-card.webp

이 주소가 200으로 이미지 자체를 보여주면 다음은 컴포넌트나 CSS 문제입니다. 이 주소가 404라면 컴포넌트가 아니라 배포 파일, 경로, 서버 반영 문제입니다.

오늘은 5줄만 채우고 AI에게 다시 묻습니다

이미지 오류를 길게 설명할 필요는 없습니다. 아래 5줄을 채우면 AI가 원인을 훨씬 좁게 볼 수 있습니다.

화면에서 안 보이는 이미지 src:
실제 파일 위치:
브라우저 Network의 Request URL:
Status Code와 Content-Type:
로컬에서는 보이는지, 배포에서만 깨지는지:

이 다섯 줄이 비어 있으면 AI는 추측으로 코드를 바꿉니다. 반대로 다섯 줄이 채워져 있으면 문제는 보통 public 경로, 파일명 대소문자, next/image 필수 값, 원격 이미지 설정, 배포 반영 중 하나로 줄어듭니다.

Next.js 이미지는 어렵다기보다 확인 순서가 중요합니다. 오늘은 새 컴포넌트를 만들기 전에 브라우저가 부른 이미지 주소와 실제 파일 위치를 먼저 맞추세요. 그 다음에 Image 컴포넌트와 remotePatterns를 확인하면, AI가 만든 화면을 버리지 않고 작은 수정으로 살릴 수 있습니다. 환경별 값까지 함께 흔들린다면 Next.js 환경변수 undefined 점검 순서를, 배포 로그에서 파일 자체를 못 찾는다면 Vercel Module not found 대소문자 점검을 이어서 확인합니다.

참고 출처

• Next.js Image Component: https://nextjs.org/docs/app/api-reference/components/image
• Next.js Static Assets in public: https://nextjs.org/docs/app/building-your-application/optimizing/static-assets
• Next.js next/image Un-configured Host: https://nextjs.org/docs/messages/next-image-unconfigured-host
• MDN img element: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img
• MDN error event: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/error_event

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