🔥 Trouble Shooting - Next.js 환경변수와 이미지 설정 트러블슈팅

💻 Next.js 환경변수 사용법

오늘 Next.js 프로젝트를 진행하면서 환경변수 사용 방식에 대해 다시 한번 확인했다. Vite나 다른 프레임워크에서는 import.meta.env로 환경변수에 접근하지만, Next.js에서는 process.env를 사용해야 한다.

// ❌ 잘못된 방법 (Vite 스타일)
const apiUrl = import.meta.env.VITE_API_URL;

// ✅ Next.js에서의 올바른 방법
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

또한 브라우저에서 접근 가능한 환경변수를 만들기 위해서는 반드시 NEXT_PUBLIC_ 접두사를 붙여야 한다. 이 접두사가 없는 환경변수는 서버 사이드에서만 접근 가능하다.

🚨 문제상황 : next/image 컴포넌트 오류: "구성되지 않은 호스트"

오늘 발생한 주요 이슈는 next/image 컴포넌트 관련 오류였다. League of Legends API에서 챔피언 이미지를 불러오려고 했는데 다음과 같은 오류가 발생했다:

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

Next.js에서는 보안상의 이유로 이미지를 불러올 수 있는 외부 도메인을 명시적으로 설정해야 한다. 기본적으로는 어떤 외부 도메인의 이미지도 허용하지 않는다.

✅ 해결 방법: next.config.js 설정하기

이 문제를 해결하기 위해 next.config.js 파일에 images.remotePatterns 설정을 추가했다:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "ddragon.leagueoflegends.com",
        port: "",
        pathname: "/cdn/**",
        search: "",
      },
    ],
  },
};

export default nextConfig;

이 설정은 다음과 같은 내용을 포함한다:

• protocol: 이미지 URL의 프로토콜 (http 또는 https)
• hostname: 이미지 서버의 호스트명
• port: 사용할 포트 (비워두면 기본 포트)
• pathname: 이미지 경로 패턴 (**를 사용하여 와일드카드 지정 가능)
• search: 쿼리 파라미터 (대부분의 경우 비워둠)

설정 후에는 다음과 같이 next/image 컴포넌트를 사용할 수 있게 되었다:

import Image from 'next/image';

function ChampionCard({ championName }) {
  return (
    <div>
      <Image
        src={`https://ddragon.leagueoflegends.com/cdn/15.5.1/img/champion/${championName}.png`}
        alt={championName}
        width={120}
        height={120}
      />
      <h3>{championName}</h3>
    </div>
  );
}

📝 배운 점

1. Next.js에서 환경변수는 process.env를 통해 접근하며, 브라우저에서 사용하려면 NEXT_PUBLIC_ 접두사가 필요하다.

2. next/image 컴포넌트는 보안상의 이유로 기본적으로 외부 이미지를 허용하지 않는다.

3. 외부 이미지를 사용하려면 next.config.js에 images.remotePatterns 설정을 추가해야 한다.

4. 이러한 보안 설정은 귀찮을 수 있지만, 사이트의 보안을 강화하고 악의적인 이미지 삽입을 방지하는 데 도움이 된다.

앞으로 Next.js 프로젝트에서 외부 API의 이미지를 사용할 때는 항상 next.config.js에 해당 도메인을 추가하는 것을 잊지 말아야겠다.

💡 추가 TIP

NextJs 공식문서 - next-image-unconfigured-host