Next.js next/image 외부 이미지 오류 문제 해결 경험 정리

MenuMate 프로젝트의 레시피 페이지 UI를 어느 정도 구현하고 제대로 동작하는지 실험해보고 있었습니다.

음식의 이미지, 이름, 재료 정보, 조리 순서가 제대로 불려와 렌더링 되고 있음을 확인했습니다. 혹시나 하여 다른 레시피의 경우도 살펴봤습니다. 몇 번은 문제가 없었으나 어느 순간 레시피 페이지가 렌더링 되지 않고 런타임 에러가 발생했습니다.

 

 

문제 상황  인식

런타임 에러의 에러 메시지는 다음과 같았습니다.

Invalid src prop (https://www.foodsafetykorea.go.kr/common/ecmFileView.do?ecm_file_no=...) on `next/image`, hostname "www.foodsafetykorea.go.kr" is not configured

기존에는 정상적으로 동작하던 이미지 컴포넌트에서 갑자기 에러가 발생했기 때문에, 처음에는 컴포넌트 자체의 문제를 의심했습니다.

하지만 곧 어떤 레시피의 이미지는 정상 렌더링 되고 어떤 레시피는 에러가 발생한다는 것은 컴포넌트의 문제가 아니라 데이터 차이에 의한 문제일 것이라고 생각이 바뀌었습니다.

 

그래서 제대로 동작하는 이미지의 URL과 에러 발생 URL을 비교해 봤습니다.

 

정상 동작 이미지

http://www.foodsafetykorea.go.kr/uploadimg/cook/...

 

에러 발생 이미지

https://www.foodsafetykorea.go.kr/common/ecmFileView.do?ecm_file_no=...

항목	정상 동작 이미지	에러 발생 이미지
protocol	http	https
pathname	/uploading/**	/common/**

둘의 차이점은 protocol과 pathname에 있었습니다. 

 

구글링 및 GPT와 상의 해본 결과, Next.js는 next/image는 외부 이미지를 사용할 때 보안과 최적화 때문에 외부 이미지 도메인을 명시적으로 허용해야 한다고 합니다. 즉, hostname + protocol + pathname이 모두 허용된 경우에만 렌더링된다는 것입니다.

그래서  현재 next.config.ts 의 상태를 확인해 봤습니다.

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'http',
        hostname: 'www.foodsafetykorea.go.kr',
        port: '',
        pathname: '/uploadimg/**',
      },
    ],
  },
};

export default nextConfig;

protocol과 pathname이 한 가지 경우만 허용하고 있었기 때문에 다른 형식이 올 경우, 오류가 나는 것이었습니다.

 

문제 해결

이번 테스트 사례로 인해 식약처 API는 이미지 URL 형식이 고정되어 있지 않기 때문에, 다양한 패턴을 고려하여 next.config의 허용 범위를 확장했습니다.

//수정 코드
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'http',
        hostname: 'www.foodsafetykorea.go.kr',
        port: '',
        pathname: '/uploadimg/**',
      },
      {
        protocol: 'https',
        hostname: 'www.foodsafetykorea.go.kr',
        port: '',
        pathname: '/uploadimg/**',
      },
      {
        protocol: 'http',
        hostname: 'www.foodsafetykorea.go.kr',
        port: '',
        pathname: '/common/**',
      },
      {
        protocol: 'https',
        hostname: 'www.foodsafetykorea.go.kr',
        port: '',
        pathname: '/common/**',
      },
    ],
  },
};

export default nextConfig;

 

next.config를 수정 후에는 dev 서버를 재시작 해야 하므로 재시작 후 이미지들이 정상 렌더링 되는지 확인했습니다.

protocol과 pathname이 다른 경우에도 정상 렌더링 됨이 확인되었습니다.

 

배운점

1. next/image는 단순한 img 태그가 아니다

보안 + 최적화를 위해 외부 이미지 도메인을 제한합니다. 단순히 hostname만이 아니라 protocol과 pathname까지 체크하고 next.config를 작성해야 합니다.

 

2. 외부 API는 항상 '일관되지 않은 데이터'를 줄 수도 있다

외부 API는 문제가 없을 거라 생각한 것이 이번 문제 사례의 원인이었습니다. 같은 API인데도 protocol과 pathname 등이 다른 일관되지 않았습니다. 즉, 문제의 원인은 코드가 아니라 '데이터'일 수도 있다는 것을 깨달았습니다.

 

문제 해결 과정 요약

1. 에러 메시지 확인
2. 정상/비정상 데이터 비교
3. 설정(next.config) 확인
4. 조건 불일치 발견
5. 설정 확장

Next.js의 next/image는 hostname뿐만 아니라 protocol과 pathname까지 엄격하게 검증하기 때문에, 외부 API를 사용할 경우 다양한 URL 패턴을 고려해야 한다는 것을 배웠습니다.