리그 오브 레전드 정보 앱 | 트러블 슈팅 (1): Next.js next/image 컴포넌트 오류 해결 방법

Next.js에서 외부 이미지 사용 시 발생한 오류 해결 (next/image)

 

최근에 프로젝트에서 <img> 태그 대신 Next.js의 next/image 컴포넌트를 사용하여 이미지 최적화를 적용하려고 했습니다. 하지만 기존의 외부 이미지 URL을 그대로 사용했을 때 아래와 같은 오류가 발생했습니다:

Unhandled Runtime Error
Error: Invalid src prop (https://ddragon.leagueoflegends.com/cdn/14.19.1/img/champion/Aatrox.png) on `next/image`, hostname "ddragon.leagueoflegends.com" is not configured under images in your `next.config.js`

 

문제 발생 배경

프로젝트에서 아래와 같이 <img> 태그를 사용해 이미지를 로드하고 있었습니다:

<img src="https://ddragon.leagueoflegends.com/cdn/14.19.1/img/champion/Aatrox.png" alt="Aatrox" />

 

그러나 성능 최적화와 이미지 로딩 효율성을 위해 Next.js에서 제공하는 Image 컴포넌트로 전환했습니다. Next.js에서는 next/image를 사용하여 이미지를 로드할 수 있습니다:

import Image from 'next/image';

<Image 
  src="https://ddragon.leagueoflegends.com/cdn/14.19.1/img/champion/Aatrox.png" 
  alt="Aatrox" 
  width={500} 
  height={500} 
/>

 

Image 컴포넌트를 사용했을 때, 이미지 로딩과 관련된 다양한 최적화가 자동으로 이루어지지만, 외부 URL을 사용하는 경우엔 호스트 도메인을 명시적으로 허용해야 하는 제약이 있었습니다.

문제 원인

Next.js에서는 외부 도메인의 이미지를 사용할 때 해당 도메인을 next.config.js 파일에 추가해야 합니다. 그렇지 않으면 위와 같은 오류가 발생합니다.

해결 방법

이 문제를 해결하기 위해 next.config.js 파일을 수정해야 했습니다. 제 경우, 외부 이미지를 제공하는 도메인인 ddragon.leagueoflegends.com을 허용하는 설정을 추가했습니다. 여기에서 나는 next.config.js 대신 next.config.mjs를 사용하고 있었기 때문에, 해당 파일에 아래와 같은 내용을 추가했습니다:

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    domains: ['ddragon.leagueoflegends.com'],
  },
};

export default nextConfig;

 

 

결론

이제 next/image 컴포넌트를 통해 외부 이미지가 문제없이 로드되었습니다. Next.js의 이미지 최적화를 활용할 수 있게 되었고, 이미지 로딩 성능이 개선되었습니다. 앞으로는 프로젝트에서 외부 이미지를 사용할 때 해당 도메인을 next.config.js에 추가하는 것을 잊지 말아야겠습니다.

 

배운 점

이번 경험을 통해 Next.js의 이미지 최적화 기능과 외부 자원 사용에 대한 제한 사항을 명확히 이해할 수 있었습니다. 특히, 보안 및 성능 최적화를 위해 사전 설정이 필요하다는 점을 깨달았고, 이는 프로젝트의 확장성과 유지 보수에 중요한 역할을 한다는 점을 배웠습니다. 앞으로는 이런 설정 부분을 미리 고려해, 예상치 못한 문제를 사전에 방지할 수 있도록 주의해야겠다고 느꼈습니다.

이 글이 비슷한 문제를 겪고 있는 분들께 도움이 되었길 바랍니다!