next/image로 외부 이미지 도메인 설정하다 삽질한 경험

첫 번째 에러 — hostname 설정

외부 이미지를 그냥 <Image src="https://example.com/photo.jpg" />로 쓰면 이런 에러가 난다.

Error: Invalid src prop (https://example.com/photo.jpg) on `next/image`,
hostname "example.com" is not configured under images in your `next.config.js`

Next.js는 보안상 허용된 도메인의 이미지만 최적화해준다. next.config.js에 도메인을 명시해줘야 한다.

domains 방식 (구버전)

예전에 찾은 블로그 글 보고 처음에 이렇게 설정했다.

// next.config.js
module.exports = {
  images: {
    domains: ['example.com'],
  },
}

로컬에서는 됐다. 근데 배포하고 나서 다른 이미지 URL이 추가되면서 또 에러가 났고, 알고 보니 domains는 deprecated된 방식이었다. Next.js 13부터는 remotePatterns를 쓰라고 한다.

remotePatterns 방식 (현재 권장)

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
        port: '',
        pathname: '/images/**',
      },
    ],
  },
}

pathname을 /**로 쓰면 해당 도메인의 모든 경로를 허용한다. 특정 경로만 허용하고 싶으면 /images/** 같이 좁혀서 쓸 수 있다.

여러 도메인을 허용해야 할 때는 배열에 추가하면 된다.

remotePatterns: [
  {
    protocol: 'https',
    hostname: 'example.com',
    pathname: '/**',
  },
  {
    protocol: 'https',
    hostname: 'cdn.another.com',
    pathname: '/**',
  },
],

와일드카드로 서브도메인까지 허용하기

chart.cyh-lab.com에서 외부 API의 이미지를 쓸 일이 생겼는데, 서브도메인이 환경마다 달라지는 경우가 있었다. 이럴 때는 hostname에 **를 쓰면 된다.

remotePatterns: [
  {
    protocol: 'https',
    hostname: '**.example.com', // 서브도메인 포함 전체 허용
    pathname: '/**',
  },
],

다만 이건 보안상 범위가 넓어지는 설정이라, 신뢰할 수 있는 도메인에만 쓰는 게 맞다.

설정 바꾼 뒤 반드시 서버 재시작

next.config.js를 수정하면 next dev 서버를 재시작해야 적용된다. 설정 고쳤는데 여전히 에러가 난다면 서버를 껐다 켜보는 게 먼저다. 이걸 몰라서 설정이 뭔가 잘못됐나 싶어서 한참 더 삽질했다.

정리

domains는 deprecated, remotePatterns가 현재 방식이다. 처음 설정할 때 최신 문서 기준으로 시작하는 게 낫다. Next.js는 버전업이 빠르다 보니 오래된 블로그 글 보고 따라 하면 이런 식으로 꼬이는 경우가 종종 있다.