🎉 공식문서 번역에 참여해주세요.  🐙  Github 바로가기  🐙
Docs
Pages Router
API Reference
Components
Image (Legacy)

<Image> (Legacy)

예시

Next.js 13부터 next/image 컴포넌트가 성능과 개발자 경험을 개선하기 위해 다시 작성되었습니다. 이전 버전과 호환되는 업그레이드 솔루션을 제공하기 위해 기존의 next/image는 next/legacy/image로 이름이 변경되었습니다.

새로운 next/image API 참조를 확인하세요.

Comparison

next/legacy/image와 비교하여 새로운 next/image 컴포넌트에는 다음과 같은 변경 사항이 있습니다:

  • <img> 주위의 <span> 래퍼를 제거하고 네이티브 계산 종횡비 (opens in a new tab)를 사용합니다
  • 표준 style prop 지원 추가
    • layout prop 대신 style 또는 className 사용
    • objectFit prop 대신 style 또는 className 사용
    • objectPosition prop 대신 style 또는 className 사용
  • IntersectionObserver 구현을 제거하고 네이티브 지연 로딩 (opens in a new tab)을 사용합니다
    • 네이티브 대체품이 없으므로 lazyBoundary prop 제거
    • 네이티브 대체품이 없으므로 lazyRoot prop 제거
  • loader 설정 대신 loader prop 사용
  • alt prop을 선택 사항에서 필수로 변경
  • onLoadingComplete 콜백이 <img> 요소에 대한 참조를 받도록 변경

Required Props

<Image /> 컴포넌트에는 다음 속성이 필요합니다.

src

다음 중 하나여야 합니다:

외부 URL을 사용할 때는 next.config.js의 remotePatterns에 추가해야 합니다.

width

width 속성은 layout과 sizes 속성에 따라 렌더링된 너비 또는 원본 너비(픽셀 단위)를 나타낼 수 있습니다.

layout="intrinsic" 또는 layout="fixed"를 사용할 때 width 속성은 렌더링된 너비(픽셀 단위)를 나타내므로 이미지가 표시되는 크기에 영향을 줍니다.

layout="responsive", layout="fill"을 사용할 때 width 속성은 원본 너비(픽셀 단위)를 나타내므로 종횡비에만 영향을 줍니다.

width 속성은 정적으로 가져온 이미지나 layout="fill"을 사용하는 경우를 제외하고 필수입니다.

height

height 속성은 layout과 sizes 속성에 따라 렌더링된 높이 또는 원본 높이(픽셀 단위)를 나타낼 수 있습니다.

layout="intrinsic" 또는 layout="fixed"를 사용할 때 height 속성은 렌더링된 높이(픽셀 단위)를 나타내므로 이미지가 표시되는 크기에 영향을 줍니다.

layout="responsive", layout="fill"을 사용할 때 height 속성은 원본 높이(픽셀 단위)를 나타내므로 종횡비에만 영향을 줍니다.

height 속성은 정적으로 가져온 이미지나 layout="fill"을 사용하는 경우를 제외하고 필수입니다.

Optional Props

<Image /> 컴포넌트는 필수 속성 외에도 여러 추가 속성을 허용합니다. 이 섹션에서는 Image 컴포넌트의 가장 일반적으로 사용되는 속성에 대해 설명합니다. 더 드물게 사용되는 속성에 대한 자세한 내용은 고급 Props 섹션에서 확인할 수 있습니다.

layout

뷰포트 크기가 변경됨에 따른 이미지의 레이아웃 동작입니다.

layout동작srcSetsizes래퍼와 사이저 유무
intrinsic (기본값)컨테이너 너비에 맞게 축소, 이미지 크기까지1x, 2x (imageSizes 기반)N/A예
fixedwidth와 height에 정확히 맞춤1x, 2x (imageSizes 기반)N/A예
responsive컨테이너 너비에 맞게 조정640w, 750w, ... 2048w, 3840w (imageSizes와 deviceSizes 기반)100vw예
fill컨테이너를 채우기 위해 X와 Y축 모두에서 확장640w, 750w, ... 2048w, 3840w (imageSizes와 deviceSizes 기반)100vw예

loader

URL을 해석하는 데 사용되는 사용자 정의 함수입니다. Image 컴포넌트에 loader를 prop으로 설정하면 next.config.js의 images 섹션에 정의된 기본 loader를 재정의합니다.

loader는 다음 매개변수를 받아 이미지의 URL 문자열을 반환하는 함수입니다:

다음은 사용자 정의 loader를 사용하는 예시입니다:

import Image from 'next/legacy/image'
 
const myLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}
 
const MyImage = (props) => {
  return (
    <Image
      loader={myLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

sizes

이미지가 다양한 브레이크포인트에서 얼마나 넓게 표시될지를 제공하는 문자열입니다. sizes의 값은 layout="responsive" 또는 layout="fill"을 사용하는 이미지의 성능에 큰 영향을 미칩니다. layout="intrinsic" 또는 layout="fixed"를 사용하는 이미지에는 무시됩니다.

sizes 속성은 이미지 성능과 관련하여 두 가지 중요한 목적을 수행합니다:

첫째, sizes의 값은 브라우저가 next/legacy/image의 자동 생성된 소스 세트에서 다운로드할 이미지의 크기를 결정하는 데 사용됩니다. 브라우저가 선택할 때 페이지에서 이미지의 크기를 아직 알지 못하므로 뷰포트와 같은 크기 또는 더 큰 이미지를 선택합니다. sizes 속성을 사용하면 브라우저에 이미지가 실제로 전체 화면보다 작을 것임을 알릴 수 있습니다. sizes 값을 지정하지 않으면 기본값인 100vw(전체 화면 너비)가 사용됩니다.

둘째, sizes 값은 구문 분석되어 자동 생성된 소스 세트의 값을 조정하는 데 사용됩니다. sizes 속성에 50vw와 같은 뷰포트 너비의 비율을 나타내는 크기가 포함되면, 소스 세트는 필요할 수 없는 너무 작은 값을 포함하지 않도록 조정됩니다.

예를 들어, 스타일링으로 인해 모바일 장치에서 이미지를 전체 너비로 표시하고, 태블릿에서는 2열 레이아웃, 데스크탑 디스플레이에서는 3열 레이아웃이 될 것임을 알고 있다면, 다음과 같은 sizes 속성을 포함해야 합니다:

import Image from 'next/legacy/image'
const Example = () => (
  <div className="grid-element">
    <Image
      src="/example.png"
      layout="fill"
      sizes="(max-width: 768px) 100vw,
              (max-width: 1200px) 50vw,
              33vw"
    />
  </div>
)

이 예제의 sizes는 성능 지표에 극적인 영향을 미칠 수 있습니다. 33vw 크기가 없으면 서버에서 선택된 이미지는 필요 이상으로 3배 넓어질 것입니다. 파일 크기는 너비의 제곱에 비례하므로, sizes가 없으면 사용자는 필요 이상으로 9배 큰 이미지를 다운로드하게 됩니다.

srcset 및 sizes에 대해 더 알아보세요:

quality

최적화된 이미지의 품질로, 1에서 100 사이의 정수이며 100이 최고의 품질입니다. 기본값은 75입니다.

priority

true일 경우, 이미지는 높은 우선순위로 간주되며 preload (opens in a new tab)됩니다. priority를 사용하는 이미지는 Lazy loading이 자동으로 비활성화됩니다.

Largest Contentful Paint (LCP) (opens in a new tab) 요소로 감지된 모든 이미지에 priority 속성을 사용해야 합니다. 서로 다른 이미지가 서로 다른 뷰포트 크기에서 LCP 요소가 될 수 있으므로 여러 개의 우선순위 이미지를 갖는 것이 적절할 수 있습니다.

이미지가 화면에 보일 때만 사용해야 합니다. 기본값은 false입니다.

placeholder

이미지가 로딩되는 동안 사용할 플레이스홀더입니다. 가능한 값은 blur 또는 empty이며, 기본값은 empty입니다.

blur인 경우, blurDataURL 속성이 플레이스홀더로 사용됩니다. src가 정적 가져오기에서 가져온 객체이고, 가져온 이미지가 .jpg, .png, .webp, 또는 .avif일 경우, blurDataURL이 자동으로 채워집니다.

동적 이미지의 경우, blurDataURL 속성을 제공해야 합니다. base64 생성에 도움이 되는 솔루션으로는 Plaiceholder (opens in a new tab)가 있습니다.

empty인 경우, 이미지가 로딩되는 동안 플레이스홀더가 없으며, 빈 공간만 표시됩니다.

다음과 같이 시도해 보세요:

Advanced Props

일부 경우에는 더 고급 사용이 필요할 수 있습니다. <Image /> 컴포넌트는 선택적으로 다음과 같은 고급 속성을 수용합니다.

style

기본 이미지 요소에 CSS 스타일을 전달 (opens in a new tab)할 수 있습니다.

모든 layout 모드는 이미지 요소에 고유한 스타일을 적용하며, 이러한 자동 스타일이 style prop보다 우선합니다.

또한 필수 width 및 height 속성이 스타일과 상호작용할 수 있음을 기억하세요. 이미지를 수정하기 위해 스타일링을 사용하는 경우, height="auto" 스타일도 설정해야 하며, 그렇지 않으면 이미지가 왜곡될 수 있습니다.

objectFit

layout="fill"을 사용할 때 이미지가 부모 컨테이너에 어떻게 맞춰질지를 정의합니다.

이 값은 src 이미지의 object-fit CSS 속성 (opens in a new tab)으로 전달됩니다.

objectPosition

layout="fill"을 사용할 때 이미지가 부모 요소 내에서 어떻게 위치하는지를 정의합니다.

이 값은 이미지에 적용되는 object-position CSS 속성 (opens in a new tab)으로 전달됩니다.

onLoadingComplete

이미지가 완전히 로드되고 플레이스홀더가 제거된 후 호출되는 콜백 함수입니다.

onLoadingComplete 함수는 다음 속성을 가진 객체를 하나의 매개변수로 받습니다:

loading

주의: 이 속성은 고급 사용을 위한 것입니다. 이미지를 eager로 전환하면 일반적으로 성능에 악영향을 미칩니다.

대부분의 사용 사례에 대해 이미지를 적절하게 즉시 로드하려면 priority 속성을 사용하는 것이 좋습니다.

이미지의 로딩 동작입니다. 기본값은 lazy입니다.

lazy일 경우, 이미지가 뷰포트에서 계산된 거리까지 도달할 때까지 로딩을 연기합니다.

eager일 경우, 이미지를 즉시 로드합니다.

자세히 알아보기 (opens in a new tab)

blurDataURL

src 이미지가 성공적으로 로드되기 전에 플레이스홀더 이미지로 사용되는 데이터 URL (opens in a new tab)입니다. placeholder="blur"와 결합할 때만 효과를 발휘합니다.

반드시 base64로 인코딩된 이미지여야 합니다. 확대되고 블러 처리되므로, 매우 작은 이미지(10px 이하)가 권장됩니다. 더 큰 이미지를 플레이스홀더로 포함하면 애플리케이션 성능에 악영향을 미칠 수 있습니다.

다음과 같이 시도해 보세요:

이미지에 맞는 고유 색상 데이터 URL을 생성할 수도 있습니다 (opens in a new tab).

lazyBoundary

이미지와 뷰포트의 교차를 감지하고 lazy 로딩을 트리거하는 데 사용되는 경계 상자로, margin 속성과 유사한 구문을 가진 문자열입니다. 기본값은 "200px"입니다.

이미지가 루트 문서가 아닌 스크롤 가능한 부모 요소에 중첩된 경우, lazyRoot 속성도 할당해야 합니다.

자세히 알아보기 (opens in a new tab)

lazyRoot

스크롤 가능한 부모 요소를 가리키는 React Ref (opens in a new tab)입니다. 기본값은 null(문서 뷰포트)입니다.

Ref는 DOM 요소 또는 Ref를 전달하는 (opens in a new tab) React 컴포넌트를 가리켜야 합니다.

DOM 요소를 가리키는 예시

import Image from 'next/legacy/image'
import React from 'react'
 
const Example = () => {
  const lazyRoot = React.useRef(null)
 
  return (
    <div ref={lazyRoot} style={{ overflowX: 'scroll', width: '500px' }}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </div>
  )
}

React 컴포넌트를 가리키는 예시

import Image from 'next/legacy/image'
import React from 'react'
 
const Container = React.forwardRef((props, ref) => {
  return (
    <div ref={ref} style={{ overflowX: 'scroll', width: '500px' }}>
      {props.children}
    </div>
  )
})
 
const Example = () => {
  const lazyRoot = React.useRef(null)
 
  return (
    <Container ref={lazyRoot}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </Container>
  )
}

자세히 알아보기 (opens in a new tab)

unoptimized

true일 경우, 소스 이미지는 품질, 크기 또는 형식을 변경하지 않고 그대로 제공됩니다. 기본값은 false입니다.

import Image from 'next/image'
 
const UnoptimizedImage = (props) => {
  return <Image {...props} unoptimized />
}

Next.js 12.3.0부터 이 속성은 다음과 같은 구성으로 next.config.js를 업데이트하여 모든 이미지에 적용할 수 있습니다:

next.config.js
module.exports = {
  images: {
    unoptimized: true,
  },
}

Other Props

<Image /> 컴포넌트의 다른 속성은 다음을 제외하고 기본 img 요소로 전달됩니다:

Configuration Options

Remote Patterns

악의적인 사용자로부터 애플리케이션을 보호하기 위해 외부 이미지를 사용하려면 구성이 필요합니다. 이를 통해 귀하의 계정에서 제공되는 외부 이미지만 Next.js 이미지 최적화 API에서 제공될 수 있습니다. 이러한 외부 이미지는 next.config.js 파일의 remotePatterns 속성으로 구성할 수 있습니다. 아래와 같이 설정하세요:

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

알아두면 좋은 점: 위의 예시는 next/legacy/image의 src 속성이 https://example.com/account123/로 시작해야 함을 보장합니다. 다른 프로토콜, 호스트 이름, 포트 또는 일치하지 않는 경로는 400 Bad Request 응답을 받게 됩니다. 다음은 next.config.js 파일의 remotePatterns 속성에 대한 또 다른 예시입니다:

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

알아두면 좋은 점: 위의 예시는 next/legacy/image의 src 속성이 https://img1.example.com 또는 https://me.avatar.example.com 또는 여러 개의 서브도메인으로 시작해야 함을 보장합니다. 다른 프로토콜, 포트 또는 일치하지 않는 호스트 이름은 400 Bad Request 응답을 받게 됩니다.

와일드카드 패턴은 pathname과 hostname 모두에 사용될 수 있으며, 다음과 같은 구문을 가집니다:

  • *는 단일 경로 세그먼트 또는 서브도메인과 일치
  • **는 끝의 여러 경로 세그먼트 또는 시작의 서브도메인과 일치

** 구문은 패턴의 중간에 사용될 수 없습니다.

알아두면 좋은 점: protocol, port 또는 pathname을 생략하면 와일드카드 **가 암묵적으로 적용됩니다. 이는 악의적인 사용자가 의도하지 않은 URL을 최적화할 수 있으므로 권장되지 않습니다.

Domains

경고: Next.js 14부터 악의적인 사용자로부터 애플리케이션을 보호하기 위해 엄격한 remotePatterns 사용을 권장합니다. 도메인에서 제공되는 모든 콘텐츠를 소유한 경우에만 domains를 사용하세요.

remotePatterns와 유사하게, domains 구성은 외부 이미지에 대한 허용된 호스트 이름 목록을 제공하는 데 사용할 수 있습니다.

그러나 domains 구성은 와일드카드 패턴 매칭을 지원하지 않으며, 프로토콜, 포트 또는 경로를 제한할 수 없습니다.

다음은 next.config.js 파일의 domains 속성에 대한 예시입니다:

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

Loader Configuration

Next.js 내장 이미지 최적화 API 대신 클라우드 제공업체를 사용하여 이미지를 최적화하려면 next.config.js 파일에서 loader와 path 접두사를 구성할 수 있습니다. 이를 통해 이미지의 src에 상대 URL을 사용할 수 있으며, 제공업체에 맞는 올바른 절대 URL이 자동으로 생성됩니다.

next.config.js
module.exports = {
  images: {
    loader: 'imgix',
    path: 'https://example.com/myaccount/',
  },
}

Built-in Loaders

다음의 이미지 최적화 클라우드 제공업체가 포함되어 있습니다:

다른 제공업체가 필요하면 next/legacy/image와 함께 loader 속성을 사용할 수 있습니다.

이미지 최적화는 빌드 시간에 output: 'export'로 사용할 수 없으며, 온디맨드에서만 가능합니다. output: 'export'와 함께 next/legacy/image를 사용하려면 기본 로더와 다른 로더를 사용해야 합니다. 토론 내용을 더 읽어보세요. (opens in a new tab)

Advanced

다음 구성은 고급 사용 사례에 해당하며 일반적으로 필요하지 않습니다. 아래 속성을 구성하기로 선택하면 향후 업데이트에서 Next.js 기본값에 대한 변경 사항이 무시됩니다.

Device Sizes

사용자의 예상 디바이스 너비를 알고 있다면, next.config.js의 deviceSizes 속성을 사용하여 디바이스 너비 브레이크포인트 목록을 지정할 수 있습니다. 이러한 너비는 next/legacy/image 컴포넌트가 layout="responsive" 또는 layout="fill"을 사용할 때 사용자 디바이스에 맞는 올바른 이미지가 제공되도록 하는 데 사용됩니다.

구성이 제공되지 않으면 아래의 기본값이 사용됩니다.

next.config.js
module.exports = {
  images: {
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
  },
}

Image Sizes

next.config.js 파일에서 images.imageSizes 속성을 사용하여 이미지 너비 목록을 지정할 수 있습니다. 이러한 너비는 디바이스 사이즈 배열과 결합되어 이미지 srcset (opens in a new tab)를 생성하는 데 사용되는 전체 사이즈 배열을 형성합니다.

두 개의 별도 목록이 있는 이유는 imageSizes가 sizes 속성을 제공하는 이미지에만 사용되기 때문입니다. 이 속성은 이미지가 화면의 전체 너비보다 작다는 것을 나타냅니다. 따라서 imageSizes의 사이즈는 모두 deviceSizes의 가장 작은 사이즈보다 작아야 합니다.

구성이 제공되지 않으면 아래의 기본값이 사용됩니다.

next.config.js
module.exports = {
  images: {
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
  },
}

Acceptable Formats

기본 이미지 최적화 API는 요청의 Accept 헤더를 통해 브라우저에서 지원하는 이미지 포맷을 자동으로 감지합니다.

Accept 헤더가 구성된 포맷 중 하나와 일치하면 배열에서 첫 번째 일치 항목이 사용됩니다. 따라서 배열의 순서가 중요합니다. 일치하는 항목이 없거나(또는 소스 이미지가 애니메이션인 경우) 이미지 최적화 API는 원본 이미지의 포맷으로 되돌아갑니다.

구성이 제공되지 않으면 아래의 기본값이 사용됩니다.

next.config.js
module.exports = {
  images: {
    formats: ['image/webp'],
  },
}

AVIF 지원을 다음 구성으로 활성화할 수 있습니다.

next.config.js
module.exports = {
  images: {
    formats: ['image/avif', 'image/webp'],
  },
}

알아두면 좋은 점: AVIF는 일반적으로 인코딩에 20% 더 오랜 시간이 걸리지만, WebP에 비해 20% 더 작은 크기로 압축됩니다. 이는 이미지를 처음 요청할 때 일반적으로 느리지만, 이후 캐시된 요청은 더 빨라진다는 것을 의미합니다.

Caching Behavior

다음은 기본 로더에 대한 캐싱 알고리즘을 설명합니다. 다른 모든 로더에 대해서는 클라우드 제공업체의 문서를 참조하세요.

이미지는 요청 시 동적으로 최적화되어 <distDir>/cache/images 디렉토리에 저장됩니다. 최적화된 이미지 파일은 만료될 때까지 이후 요청에 대해 제공됩니다. 만약 캐시된 파일이 만료되었지만 요청이 들어오면, 만료된 이미지는 즉시 오래된 상태로 제공됩니다. 이후 이미지는 백그라운드에서 다시 최적화(재검증이라고도 함)되어 새로운 만료 날짜와 함께 캐시에 저장됩니다.

이미지의 캐시 상태는 x-nextjs-cache(Vercel에 배포된 경우 x-vercel-cache`) 응답 헤더의 값을 읽음으로써 확인할 수 있습니다. 가능한 값은 다음과 같습니다:

  • MISS - 경로가 캐시에 없음 (최초 방문 시 최대 한 번 발생)
  • STALE - 경로가 캐시에 있지만 재검증 시간을 초과하여 백그라운드에서 업데이트될 예정
  • HIT - 경로가 캐시에 있으며 재검증 시간을 초과하지 않음

만료(또는 최대 연령)는 minimumCacheTTL 구성이나 상위 이미지의 Cache-Control 헤더 중 더 큰 값으로 정의됩니다. 구체적으로, Cache-Control 헤더의 max-age 값이 사용됩니다. s-maxage와 max-age가 모두 발견되면 s-maxage가 우선시됩니다. max-age는 CDN 및 브라우저를 포함한 모든 다운스트림 클라이언트에도 전달됩니다.

  • 상위 이미지에 Cache-Control 헤더가 포함되어 있지 않거나 값이 매우 낮을 경우, minimumCacheTTL을 구성하여 캐시 기간을 늘릴 수 있습니다.
  • deviceSizes 및 imageSizes를 구성하여 생성 가능한 이미지의 총 수를 줄일 수 있습니다.
  • formats를 구성하여 여러 포맷을 비활성화하고 단일 이미지 포맷을 사용할 수 있습니다.

Minimum Cache TTL

캐시된 최적화된 이미지의 생존 시간(TTL)을 초 단위로 구성할 수 있습니다. 많은 경우, 정적 이미지 가져오기를 사용하는 것이 더 좋습니다. 이 방법은 파일 내용을 자동으로 해시하고 immutable의 Cache-Control 헤더로 이미지를 영구적으로 캐시합니다.

next.config.js
module.exports = {
  images: {
    minimumCacheTTL: 60,
  },
}

최적화된 이미지의 만료(또는 최대 연령)는 minimumCacheTTL 또는 상위 이미지의 Cache-Control 헤더 중 더 큰 값으로 정의됩니다.

이미지마다 캐싱 동작을 변경해야 할 경우, headers를 구성하여 상위 이미지에 Cache-Control 헤더를 설정할 수 있습니다(예: /some-asset.jpg, /_next/image 자체는 아님).

현재 캐시를 무효화하는 메커니즘은 없으므로 minimumCacheTTL을 낮게 유지하는 것이 좋습니다. 그렇지 않으면 src 속성을 수동으로 변경하거나 <distDir>/cache/images를 삭제해야 할 수도 있습니다.

Disable Static Imports

기본 동작은 import icon from './icon.png'와 같은 정적 파일을 가져온 후 이를 src 속성에 전달할 수 있게 해줍니다.

경우에 따라, 가져오기가 다르게 동작하기를 기대하는 다른 플러그인과 충돌할 경우 이 기능을 비활성화하고 싶을 수 있습니다.

정적 이미지 가져오기를 next.config.js 내에서 비활성화할 수 있습니다.

next.config.js
module.exports = {
  images: {
    disableStaticImages: true,
  },
}

Dangerously Allow SVG

기본 로더는 몇 가지 이유로 SVG 이미지를 최적화하지 않습니다. 첫째, SVG는 벡터 형식으로 손실 없이 크기를 조절할 수 있습니다. 둘째, SVG는 HTML/CSS와 유사한 많은 기능을 가지고 있어 적절한 콘텐츠 보안 정책(CSP) 헤더가 없으면 취약점이 발생할 수 있습니다.

따라서 src 속성이 SVG임이 확실할 때는 unoptimized 속성을 사용하는 것이 좋습니다. 이는 src가 ".svg"로 끝날 때 자동으로 발생합니다.

그러나 기본 이미지 최적화 API로 SVG 이미지를 제공해야 하는 경우, next.config.js 내에서 dangerouslyAllowSVG를 설정할 수 있습니다:

next.config.js
module.exports = {
  images: {
    dangerouslyAllowSVG: true,
    contentDispositionType: 'attachment',
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
}

또한, 브라우저가 이미지를 다운로드하도록 강제하기 위해 contentDispositionType을 설정하고, 이미지에 포함된 스크립트가 실행되지 않도록 contentSecurityPolicy를 설정하는 것이 강력히 권장됩니다.

contentDispositionType

기본 로더는 추가 보호를 위해 Content-Disposition (opens in a new tab) 헤더를 attachment로 설정합니다. API는 임의의 원격 이미지를 제공할 수 있기 때문입니다.

기본 값은 attachment로, 이를 통해 브라우저는 직접 방문할 때 이미지를 다운로드하도록 강제됩니다. 이는 dangerouslyAllowSVG가 true일 때 특히 중요합니다.

선택적으로 inline을 구성하여 브라우저가 직접 방문할 때 이미지를 다운로드하지 않고 렌더링할 수 있도록 할 수 있습니다.

next.config.js
module.exports = {
  images: {
    contentDispositionType: 'inline',
  },
}

Animated Images

기본 로더는 애니메이션 이미지에 대해 자동으로 이미지 최적화를 우회하고 이미지를 있는 그대로 제공합니다.

애니메이션 파일에 대한 자동 감지는 최선의 노력으로 이루어지며 GIF, APNG 및 WebP를 지원합니다. 특정 애니메이션 이미지에 대해 명시적으로 이미지 최적화를 우회하고 싶다면 unoptimized 속성을 사용하세요.

Version History

VersionChanges
v13.0.0next/image renamed to next/legacy/image
HeadImage