[내보내번] Next.js docs - next/image (v12.1.1)

내보내번(내가 보려고 내가 번역한...) Next.js docs

2022년 4월 15일 기준 Next.js 공식 문서로 업데이트했다. (v12.1.1)

이전 버전 문서는 아래에서 확인할 수 있다. 
2021.04.01 - [Next.js] - [내보내번] Next.js docs - next/image

※ 영어 전공자도 해외 유학파도 아니기에 번역에는 의역, 오역, 구글 번역이 무수히 많을 수 있으며, 혼자 공식문서를 참조해가며 번역하다 보니 오타도 많을 수 있다. 정확한 내용은 공식문서를 직접 살펴보거나 다른 정보들을 더 찾아보는 것을 추천한다.

(하지만 댓글 피드백도 환영합니다😃 )

Next.js 공식문서 확인하기>>

next/image | Next.js

---

Note: This is API documentation for the Image Component and Image Optimization. For a feature overview and usage information for images in Next.js, please see Images.
노트: 이 API 문서는 이미지 컴포넌트와 이미지 최적화를 위한 것이다. Next.js의 이미지에 대한 기능 개요와 사용법에 대한 정보는 Images 문서를 살펴보라. 

2021.03.31 - [Next.js] - [내보내번] Next.js docs - Image Component and Image Optimization

[내보내번] Next.js docs - Image Component and Image Optimization

 

Required Props 

The <Image /> component requires the following properties.

<Image /> 컴포넌트는 아래의 속성들이 요구된다: 

src

Must be one of the following:

1. A statically imported image file, or
2. A path string. This can be either an absolute external URL, or an internal path depending on the loader prop or loader configuration.

When using an external URL, you must add it to domains in next.config.js.

아래의 사항 중 한 가지는 반드시 요구된다:

1. 정적으로 가져온 이미지 파일이나
2. 경로 스트링. 이것은 외부 절대 URL이거나 loader prop이나 loader 설정에 따른 내부 경로일 수도 있다. 

외부 URL을 사용하는 경우 next.config.js의 domains에 추가해야만 한다.

width

The `width` property can represent either the rendered width or original width in pixels, depending on the `layout` and `sizes` properties.

When using `layout="intrinsic"`, `layout="fixed"`, or `layout="raw"` without `sizes`, the `width` property represents the rendered width in pixels, so it will affect how large the image appears.

When using `layout="responsive"`, `layout="fill"`, or `layout="raw"` with `sizes`, the `width` property represents the original width in pixels, so it will only affect the aspect ratio.

The `width` property is required, except for statically imported images, or those with layout="fill".

`width` 속성은 `layout` 이나 `sizes` 속성에 따라 픽셀로 렌더된 너비 혹은 원본의 너비를 픽셀로 나타낼 수 있다. 

`sizes` 속성이 없이 `layout="intrinsic"`, `layout="fixed"` 혹은 `layout="raw"`를 사용할 때 `width` 속성은 렌더된 너비를 픽셀로 나타낸다. 그렇기 때문에 이미지가 얼마나 크게 보여지는지에 영향을 미칠 것이다. 

`sizes` 속성과 함께 `layout="responsive"`, `layout="fill"` 혹은 `layout="raw"`를 사용할 때 `width` 속성은 원본의 너비를 픽셀로 나타낸다. 그렇기 때문에 이미지의 비율에만 영향을 미칠 것이다. 

정적으로 가져오는 이미지나 layout="fill"이 아닌 경우를 제외하고 `width` 속성이 요구된다. 

height

The height property can represent either the rendered height or original height in pixels, depending on the layout and sizes properties.

When using layout="intrinsic", layout="fixed", or layout="raw" without sizes, the height property represents the rendered height in pixels, so it will affect how large the image appears.

When using layout="responsive", layout="fill", or layout="raw" with sizes, the height property represents the original height in pixels, so it will only affect the aspect ratio.

The height property is required, except for statically imported images, or those with layout="fill".

`height` 속성은 `layout` 이나 `sizes` 속성에 따라 픽셀로 렌더된 너비 혹은 원본의 너비를 픽셀로 나타낼 수 있다. 

`sizes` 속성이 없이 `layout="intrinsic"`, `layout="fixed"` 혹은 `layout="raw"`를 사용할 때 `height` 속성은 렌더된 높이를 픽셀로 나타낸다. 그렇기 때문에 이미지가 얼마나 크게 보여지는지에 영향을 미칠 것이다.

`sizes` 속성과 함께 `layout="responsive"`, `layout="fill"` 혹은 `layout="raw"`를 사용할 때 `height` 속성은 원본의 높이를 픽셀로 나타낸다. 그렇기 때문에 이미지의 비율에만 영향을 미칠 것이다. 

정적으로 가져오는 이미지나 layout="fill"이 아닌 경우를 제외하고 `height` 속성이 요구된다. 

 

Optional Props

The <Image /> component accepts a number of additional properties beyond those which are required. This section describes the most commonly-used properties of the Image component. Find details about more rarely-used properties in the Advanced Props section.

<Image /> 컴포넌트에 필수적인 속성 외에도 많은 추가 속성들을 허용한다. 이 부분은 이미지 컴포넌트에서 가장 흔히 사용되는 속성들에 대해 서술한다. 흔히 사용되지 않는 속성들에 대해서는 Advanced Props 섹션에서 더 자세한 점에 대해 살펴보라. 

layout

The layout behavior of the image as the viewport changes size. 

`layout`	Behavior	`srcSet`	`sizes`	Has wrapper and sizer
`instrinsic` (default)	Scale down to fit width of container, up to image size	`1x`, `2x` (based on imageSizes)	N/A	yes
`fixed`	Sized to `width` and `height` exactly	`1x`, `2x` (based on imageSizes)	N/A	yes
`responsive`	Scale to fit width of container	`640w`, `750w`, ... `2048w`, `3840w` (based on imageSizes and deviceSizes)	`100vw`	yes
`fill`	Grow in both X and Y axes to fill container	`640w`, `750w`, ... `2048w`, `3840w` (based on imageSizes and deviceSizes)	`100vw`	yes
`raw`*	Insert the image element with no automatic layout behavior	Behaves like responsive if the image has the sizes prop, and like fixed if it does not	optional	no

`layout`	Behavior	`srcSet`	`sizes`	Has wrapper and sizer
`instrinsic` (기본값)	컨테이너의 너비에 맞추기 위해 이미지 크기 축소, 이미지 크기에 달려있음	`1x`, `2x` (imageSizes에 따라 *하단의 Image Sizes 소제목 참조)	N/A	yes
`fixed`	정확한 `width`와 `height`에 맞춤	`1x`, `2x` (imageSizes에 따라 *하단의 Image Sizes 소제목 참조)	N/A	yes
`responsive`	컨테이너의 너비에 맞춰 크기 조정	`640w`, `750w`, ... `2048w`, `3840w` (imageSizes 와 deviceSizes에 따라 *하단의 Image Sizes와 Device Sizes 소제목 참조)	`100vw`	yes
`fill`	컨테이너에 채우기 위해 X, Y축 모두를 키움	`640w`, `750w`, ... `2048w`, `3840w` (imageSizes 와 deviceSizes에 따라 *하단의 Image Sizes와 Device Sizes 소제목 참조)	`100vw`	yes
`raw`*	자동 레이아웃 동작없이 이미지 요소 추가	속성을 가지고 있는 경우 반응형으로 동작하고 그렇지 않은 경우 고정됨	optional	no

• Demo the intrinsic layout (default)
  • When intrinsic, the image will scale the dimensions down for smaller viewports but maintain the original dimensions for larger viewports.
• Demo the fixed layout
  • When fixed, the image dimensions will not change as the viewport changes (no responsiveness) similar to the native img element.
• Demo the responsive layout
  • When responsive, the image will scale the dimensions down for smaller viewports and scale up for larger viewports.
  • Ensure the parent element uses display: block in their stylesheet.
• Demo the fill layout
  • When fill, the image will stretch both width and height to the dimensions of the parent element, provided the parent element is relative.
  • This is usually paired with the objectFit property.
  • Ensure the parent element has position: relative in their stylesheet.

 

• When raw*, the image will be rendered as a single image element with no wrappers, sizers or other responsive behavior.
  • If your image styling will change the size of a raw image, you should include the sizes property for proper image serving. Otherwise your image will receive a fixed height and width.
  • The other layout modes are optimized for performance and should cover nearly all use cases. It is recommended to try to use those modes before using raw.
• Demo background image

 

 

뷰포트의 크기가 변경될 때 이미지의 레이아웃 동작이다. (layout 속성의 동작을 의미하는 듯함. ) 

• intrinsic 레이아웃 데모 (기본값)
  • 값이 intrinsic인 경우, 이미지는 작은 뷰포트에서는 크기가 줄어들지만 더 큰 뷰포트에서는 본래의 크기를 유지할 것이다. 
• fixed 레이아웃 데모
  • 값이 fixed인 경우, native img 요소와 비슷하게 뷰포트의 크기가 변해도(반응 없음 - 반응형이 아니라는 의미 같음) 이미지의 크기가 변하지 않는다. 
• responsive 레이아웃 데모
  • 값이 responsive인 경우, 이미지가 작은 뷰포트에서는 크기가 줄어들고 더 큰 뷰포트에서는 크기가 커진다. 
  • 부모 요소가 스타일시트에서 `display: block`을 사용하는지 확인하라.
• fill 레이아웃 데모
  • 값이 fill일 때, 부모 요소가 relative인 경우 부모 요소의 크기에 맞춰 너비와 높이가 늘어난다.
  • 보통은 objectFit 속성과 함께 사용한다.
  • 부모 요소가 스타일시트에서 `display: relative`를 사용하는지 확인하라.
• raw 일 때, 이미지는 wrapper, sizer나 다른 반응형 동작없이 단일 이미지 요소로 렌더링 된다.
  • 이미지의 스타일이 `raw` 이미지의 크기를 변경하는 경우, 적절한 이미지 제공을 위해서 `sizes` 속성을 포함시켜야한다. 그렇지 않으면 이미지의 높이와 너비가 고정된다.  
  • 다른 레이아웃 모드들은 성능을 위해서 최적화 되어 있고 거의 모든 경우에 사용되어야한다. 그렇기 때문에 `raw`를 사용하기 전에 그러한 모드들을 사용하는 것을 추천한다. 
• 백그라운드 이미지 데모

 

loader

A custom function used to resolve URLs. Setting the loader as a prop on the Image component overrides the default loader defined in the images section of next.config.js.

A loader is a function returning a URL string for the image, given the following parameters:

• src
• width
• quality

Here is an example of using a custom loader with next/image:

URL을 확인하는 데 사용되는 사용자 지정 함수. 이미지 컴포넌트에서 loader를 prop으로 설정하면 next.config.js의 이미지 영역에 정의된 기본 loader를 오버라이드한다. 

Loader는 아래와 같은 파라미터가 주어지면 이미지를 위한 URL 문자열을 반환하는 함수이다: 

• src
• width
• quality

아래는 next/image와 함께 커스텀 loader를 사용하는 예제이다: 

import Image from 'next/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

A string that provides information about how wide the image will be at different breakpoints. Defaults to 100vw (the full width of the screen) when using layout="responsive" or layout="fill".

If you are using layout="fill" or layout="responsive", it's important to assign sizes for any image that takes up less than the full viewport width.

For example, when the parent element will constrain the image to always be less than half the viewport width, use sizes="50vw". Without sizes, the image will be sent at twice the necessary resolution, decreasing performance.

If you are using layout="intrinsic" or layout="fixed", then sizes is not needed because the upperbound width is constrained already.

Learn more.

다양한 중단점(breakpoints)에서 이미지가 어느 너비를 가질 것인지에 대한 정보를 제공해주는 문자열이다. layout="responsive"와 layout="fill"을 사용할 때 기본값은 100vw(화면의 전체 너비)이다.

layout="fill"이나 layout="responsive"를 사용하고 있는 경우, 전체 뷰포트 너비보다 적게 차지하는 모든 이미지에 대해 크기를 지정하는 것이 중요하다. 

예를 들면, 부모 요소가 이미지를 항상 뷰포트 너비의 절반 미만으로 제한한다면 sizes="50vw"를 사용한다. sizes가 없으면 이미지가 필요한 해상도의 두 배로 전송되어 성능이 저하된다. 

layout="intrinsic이나 layout="fixed"를 사용하고 있는 경우, 너비의 상한선에 이미 제약이 걸려있기 때문에 sizes는 필요하지 않다.

  

quality

The quality of the optimized image, an integer between 1 and 100 where 100 is the best quality. Defaults to 75.

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

priority

When true, the image will be considered high priority and preload. Lazy loading is automatically disabled for images using priority.

You should use the priority property on any image detected as the Largest Contentful Paint (LCP) element. It may be appropriate to have multiple priority images, as different images may be the LCP element for different viewport sizes.

Should only be used when the image is visible above the fold. Defaults to false.

true인 경우 이미지가 높은 우선순위와 preload로 간주된다. priority를 사용한 이미지들은 lazy loading이 자동으로 비활성화된다. 

Largest Contentful Paint(LCP) 요소로 감지되는 어떤 이미지든 priority 속성을 사용해야 한다. 다른 이미지는 다른 뷰포트 크기에 대한 LCP 요소일 수 있기 때문에 여러 우선순위 이미지를 갖는 것이 적절할 수 있다.

이미지가 웹 사이트 상단부*에 보여야 하는 경우에만 사용해야 한다. 기본값은 false이다. 

(*above the fold: 웹 사이트에서 스크롤을 내리지 않고 제일 먼저 볼 수 있는 영역, 1면의 상단부 - 네이버 오픈사전)

 

placeholder

A placeholder to use while the image is loading. Possible values are 'blur' or 'empty'. Defaults to empty.

When blur, the blurDataURL property will be used as the placeholder. If src is an object from a static import and the imported image is .jpg, .png, .webp or .avif, then blurDataURL will automatically be populated.

For dynamic images, you must provide the blurDataURL property. Solutions such as Plaiceholder can help with base64 generation.

When empty, there will be no placeholder while the image is loading, only empty space.

Placeholder는 이미지가 로드되는 동안 사용하는 것이다. 가능한 값은 blur나 empty이다. 기본값은 empty. 

blur일 때, blurDataURL 속성이 placeholder로 사용될 것이다. 만일 src가 정적으로 가져오는 개체이고 이미지의 확장자가 .jpg, .png,  .webp 혹은 .avif인 경우, blurDataURL은 자동으로 채워질 것이다. 

동적 이미지의 경우 blurDataURL 속성을 제공해야한다. Plaiceholder와 같은 솔루션이 base64 생성에 도움이 될 수 있습니다.

empty일 때, 이미지가 로드되는 동안 어떤 placeholder도 없을 것이며 빈 공간만 보일 것이다. 

Try it out:

• Demo the blur placeholder
• Demo the shimmer effect with blurDataURL prop
• Demo the color effect with blurDataURL prop

 

Advanced Props

In some cases, you may need more advanced usage. The <Image /> component optionally accepts the following advanced properties.

어떤 경우에서는 더 고급 사용법이 필요할 수도 있다. <Image /> 컴포넌트는 선택적으로 아래와 같은 고급 속성들을 허용한다. 

style

Allows passing CSS styles to the underlying image element.

Note that all layout modes other than "raw"* apply their own styles to the image element, and these automatic styles take precedence over the style prop.

CSS 스타일을 기본 이미지 요소에 전달할 수 있다.

"raw"를 제외한 모든 레이아웃 모드들은 각자의 스타일을 이미지 요소에 적용시킨다는 점을 기억하라. 그리고 이러한 자동 스타일은 style 속성보다 우선순위를 가진다. 

 

objectFit

Defines how the image will fit into its parent container when using layout="fill".
This value is passed to the object-fit CSS property for the src image.

layout="fill" 사용 시 이미지가 부모 컨테이너에 맞는(fit) 방식을 정의한다. 
이 값은 소스 이미지의 object-fit CSS 속성으로 전달된다. 

 

objectPosition

Defines how the image is positioned within its parent element when using layout="fill".
This value is passed to the object-position CSS property applied to the image.

layout="fill" 사용시 부모 요소의 내부에서 이미지 배치 방식을 정의한다. 
이 값은 이미지의 object-position CSS 속성으로 전달된다. 

 

onLoadingComplete

A callback function that is invoked once the image is completely loaded and the placeholder has been removed.
The onLoadingComplete function accepts one parameter, an object with the following properties:

• naturalWidth
• naturalHeight

이미지가 완전히 로드되고 placeholder가 사라지면 호출되는 콜백 함수이다. 
onLoadingComplete 함수는 아래의 속성들로 이루어진 객체를 하나의 파라미터로 받는다:

• naturalWidth
• naturalHeight

 

loading

Attention: This property is only meant for advanced usage. Switching an image to load with eager will normally hurt performance.
We recommend using the priority property instead, which properly loads the image eagerly for nearly all use cases.
주의: 이 속성은 고급 사용법을 위함이다. 대개 이미지를 로드하기 위한 loading 값을 eagar로 바꾸면 성능 저하에 영향을 미친다. (아래의 속성을 설명하는 부분을 먼저 읽는 것이 주의 사항을 이해하는데 도움이 됨.)
대신 거의 모든 경우에 이미지를 적절히 로드하는 priority 속성을 사용하는 것을 권장한다. 

The loading behavior of the image. Defaults to lazy.

When lazy, defer loading the image until it reaches a calculated distance from the viewport.

When eager, load the image immediately.

Learn more

이미지의 로딩 동작에 대한 속성. 기본값은 lazy이다. 

값이 lazy인 경우, 뷰포트로부터 계산된 거리에 도달할 때까지 이미지 로딩을 미룬다. 

값이 eager인 경우, 이미지를 즉시 로드한다. 

 

blurDataURL

A Data URL to be used as a placeholder image before the src image successfully loads. Only takes effect when combined with placeholder="blur".

Must be a base64-encoded image. It will be enlarged and blurred, so a very small image (10px or less) is recommended. Including larger images as placeholders may harm your application performance.

Data URL은 src 이미지가 성공적으로 로드되지 전에 placeholder 이미지로 사용될 것이다. placeholder="blur"와 결합된 경우에만 적용된다. 

base64-encoded 이미지여야만 한다. 확대되어 흐려지므로 아주 작은 이미지(10픽셀이나 더 작은)를 권장한다. placeholder로 큰 이미지를 포함하는 경우 당신의 어플리케이션 성능에 해가 될 수 있다. 

Try it out:

• Demo the default blurDataURL prop
• Demo the shimmer effect with blurDataURL prop
• Demo the color effect with blurDataURL prop

You can also generate a solid color Data URL to match the image.

이미지와 일치하도록 단색 Data URL을 생성할 수도 있다.

 

lazyBoundary

A string (with similar syntax to the margin property) that acts as the bounding box used to detect the intersection of the viewport with the image and trigger lazy loading. Defaults to "200px".

이미지와 뷰포트의 교차를 감지하고 lazy loading을 트리거하는 데 사용되는 경계 상자 역할을 하는 문자열이다. (margin 속성과 유사한 구문). 기본값은 200px이다.

Learn more

 

lazyRoot

A React Ref pointing to the scrollable parent element. Defaults to null (the document viewport).

The Ref must point to a DOM element or a React component that forwards the Ref to the underlying DOM element.

React Ref는 스크롤가능한 부모 요소를 가리킨다. 기본값은 null (document 뷰포트)이다.

Ref는 DOM 요소나 기본 DOM 요소에 Ref를 전달하는 React 컴포넌트를 가리켜야 한다. 

Example pointing to a DOM element - DOM 요소를 가리키는 예제

import Image from 'next/image'
import React from 'react'

const lazyRoot = React.useRef(null)

const Example = () => (
  <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>
)

Example pointing to a React component - React 컴포넌트를 가리키는 예제

import Image from 'next/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>
  )
}

Learn more

 

unoptimized

When true, the source image will be served as-is instead of changing quality, size, or format. Defaults to false.

값이 true인 경우, 원본 이미지의 품질, 크기, 포맷을 변경하는 대신 그대로 제공될 것이다. 기본값은 false이다.

 

Other Props

Other properties on the <Image /> component will be passed to the underlying img element with the exception of the following:

• srcSet. Use Device Sizes instead.
• ref. Use onLoadingComplete instead.
• decoding. It is always "async".

<Image /> 컴포넌트의 다른 속성들은 아래에 대해서는 제외하고 기본 img 속성으로 전달될 것이다: 

• srcSet. 대신 Device Sizes를 사용하라.
• ref. 대신 onLoadingComplete를 사용하라.
• decoding. 항상 async이다. 

 

Configuration Options

Domains

To protect your application from malicious users, you must define a list of image provider domains that you want to be served from the Next.js Image Optimization API. This is configured in with the domains property in your next.config.js file, as shown below:

악성 사용자로부터 당신의 어플리케이션을 보호하기 위해서는, Next.js 이미지 최적화 API에 제공할 이미지 제공자 도메인 목록을 정해야 한다. 아래에 보이는 것과 같이 next.config.js 파일의 도메인 속성으로 설정된다.

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

 

Loader Configuration

If you want to use a cloud provider to optimize images instead of using the Next.js built-in Image Optimization API, you can configure the loader and path prefix in your next.config.js file. This allows you to use relative URLs for the Image src and automatically generate the correct absolute URL for your provider.

만일 Next.js 내장 이미지 최적화 API를 사용하는 대신 이미지를 최적화하기 위해 클라우드 제공자를 사용하길 원한다면, 자신의 next.config.js 파일에서 loader와 경로 prefix를 구성할 수 있다. 이를 통해서 이미지 경로를 위한 상대 URL을 사용하는 것과 제공자에 대한 올바른 절대 URL을 자동으로 생성하는 것이 가능해진다. 

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

 

Built-in Loaders

The following Image Optimization cloud providers are included:

• Default: Works automatically with next dev, next start, or a custom server
• Vercel: Works automatically when you deploy on Vercel, no configuration necessary. Learn more
• Imgix: loader: 'imgix'
• Cloudinary: loader: 'cloudinary'
• Akamai: loader: 'akamai'
• Custom: loader: 'custom' use a custom cloud provider by implementing the loader prop on the next/image component

If you need a different provider, you can use the loader prop with next/image.

Images can not be optimized at build time using `next export`, only on-demand. To use `next/image` with `next export`, you will need to use a different loader than the default. Read more in the discussion.

The next/image component's default loader uses squoosh because it is quick to install and suitable for a development environment. When using next start in your production environment, it is strongly recommended that you install sharp by running yarn add sharp in your project directory. This is not necessary for Vercel deployments, as sharp is installed automatically.

다음 이미지 최적화 클라우드 제공자가 포함된다:

• 기본값: next dev, next start 나 커스텀 서버와 자동으로 작동
• Vercel: Vercel에 배포하면 자동으로 작동, 구성 필요 없음. Learn more
• Imgix: loader: 'imgix'
• Cloudinary: loader: 'cloudinary'
• Akamai: loader: 'akamai'
• 커스텀: loader: 'custom' 은 next/image 컴포넌트에 loader prop을 구현하여 커스텀 클라우드 제공자를 사용함.

만약 다른 제공자가 필요한 경우, next/image와 함께 loader prop을 사용할 수 있다.

`next export`를 사용하면 이미지는 빌드 시간에 최적화 될 수 없고 요구에 따라서만 가능하다. `next/image`를 `next export`와 함께 사용하기 위해서는 기본 로더가 아닌 다른 로더를 사용해야한다. 링크의 discussion에서 더 읽어보라. 

next/image 컴포넌트의 기본 loader는 squoosh를 사용하는데 설치가 빠르고 개발 환경에 적합하기 때문이다. 운영 환경에서 next start를 사용하는 경우 프로젝트 디렉토리에서 yarn add sharp를 실행하여 sharp를 설치하는 것을 강력 추천한다. Vercel에 배포하는 경우라면 자동으로 sharp가 설치되기 때문에 불필요하다. 

 

Advanced

The following configuration is for advanced use cases and is usually not necessary. If you choose to configure the properties below, you will override any changes to the Next.js defaults in future updates.

아래의 구성은 고급 사용을 위한 경우이며 대개는 필요하지 않다. 당신이 아래의 속성들에 대해 구성하길 선택한다면, 앞으로 있을 업데이트에서의 Next.js 기본값에 대한 변경사항을 오버라이드 할 것이다. 

Device Sizes

If you know the expected device widths of your users, you can specify a list of device width breakpoints using the deviceSizes property in next.config.js. These widths are used when the next/image component uses layout="responsive" or layout="fill" to ensure the correct image is served for user's device.

If no configuration is provided, the default below is used.

사용자의 예상 기기 너비를 알고 있는 경우, 기기 너비 중단점 목록을 next.config.js의 deviceSizes 속성을 사용하여 명시할 수 있다. 이 너비들은 next/image 컴포넌트가 layout="responsive"나 layout="fill"인 경우 사용자의 기기에 올바른 이미지 제공을 보장하기 위해 사용된다. 

어떠한 구성이 제공되지 않는다면 아래의 기본값이 사용된다. 

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

 

Image Sizes

You can specify a list of image widths using the images.imageSizes property in your next.config.js file. These widths are concatenated with the array of device sizes to form the full array of sizes used to generate image srcsets.

The reason there are two separate lists is that imageSizes is only used for images which provide a sizes prop, which indicates that the image is less than the full width of the screen. Therefore, the sizes in imageSizes should all be smaller than the smallest size in deviceSizes.

If no configuration is provided, the default below is used.

next.config.js 파일의 images.imageSizes 속성을 사용하여 이미지 너비 목록을 명시할 수 있다. 이 너비들은 기기 너비(device sizes) 배열과 연결되어 이미지 srcset을 생성하는 데 사용되는 전체 크기 배열을 형성한다. 

여기에 두 가지 분리된 목록이 있는 이유는 imageSizes가 sizes prop을 제공하는 이미지에만 사용되기 때문이다. 이는 이미지가 화면의 전체 너비보다 작다는 것을 나타낸다. 그러므로, imageSizes의 sizes 모두는 deviceSizes의 가장 작은 크기보다 작아야만 한다. 

어떠한 구성이 제공되지 않는다면 아래의 기본값이 사용된다.

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

 

Acceptable Formats

The default Image Optimization API will automatically detect the browser's supported image formats via the request's Accept header.

If the Accept head matches more than one of the configured formats, the first match in the array is used. Therefore, the array order matters. If there is no match, the Image Optimization API will fallback to the original image's format.

If no configuration is provided, the default below is used.

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

Accept 헤더가 구성된 포맷 중 하나 이상과 일치되는 경우, 배열의 첫 번째 매치된 것을 사용한다. 그러므로 배열의 순서가 중요하다. 일치하는 것이 없으면, 이미지 최적화 API는 원본 이미지의 포맷으로 대체된다. 

어떠한 구성이 제공되지 않는다면 아래의 기본값이 사용된다.

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

You can enable AVIF support with the following configuration.
아래의 구성을 통해 AVIF 지원을 활성화할 수 있다. 

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

Note: AVIF generally takes 20% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower and then subsequent requests that are cached will be faster.
노트: AVIF는 대개 인코딩하는데 20% 나 더 오래 걸리지만 WebP와 비교할 때 20% 더 작게 압축한다. 이 말의 의미는 이미지가 처음 요청되었을 때 보통 더 느리고 캐시된 그 다음의 요청부터는 더 빠르다. 

 

Caching Behavior

The following describes the caching algorithm for the default loader. For all other loaders, please refer to your cloud provider's documentation.

Images are optimized dynamically upon request and stored in the <distDir>/cache/images directory. The optimized image file will be served for subsequent requests until the expiration is reached. When a request is made that matches a cached but expired file, the expired image is served stale immediately. Then the image is optimized again in the background (also called revalidation) and saved to the cache with the new expiration date.

The cache status of an image can be determined by reading the value of the `x-nextjs-cache` response header. The possible values are the following:

• MISS - the path is not in the cache (occurs at most once, on the first visit)
• STALE - the path is in the cache but exceeded the revalidate time so it will be updated in the background
• HIT - the path is in the cache and has not exceeded the revalidate time

The expiration (or rather Max Age) is defined by either the minimumCacheTTL configuration or the upstream server's `Cache-Control` header, whichever is larger. Specifically, the `max-age` value of the `Cache-Control` header is used. If both `s-maxage` and `max-age` are found, then `s-maxage` is preferred.

• You can configure minimumCacheTTL to increase the cache duration when the upstream image does not include `Cache-Control` header or the value is very low.
• You can configure deviceSizes and imageSizes to reduce the total number of possible generated images.
• You can configure formats to disable multiple formats in favor of a single image format.

아래의 설명은 기본 loader의 캐싱 알고리즘에 대한 것이다. 다른 loader에 대해서는 당신의 클라우드 제공자의 문서를 참조하길 바란다. 

이미지는 요청에 따라서 동적으로 최적화되고 <distDir>/cache/images 디렉토리에 저장된다. 최적화된 이미지 파일은 만료기간 전까지 후속 요청에 대해서 제공될 것이다. 캐시가 되어 있지만 만료된 파일에 대한 요청이 이루어지면, 만료된 이미지는 즉시 오래된 이미지로 제공된다. 그 이미지는 백그라운드에서 다시 최적화되고(재검증이라고 불림) 새로운 만료일자로 캐시되어 저장된다. 

이미지의 캐시 상태는 `x-nextjs-cache` 응답 헤더의 값을 읽어 확인할 수 있다. 가능한 값들은 아래와 같다.

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

만료기간(혹은 Max Age)은 minimumCacheTTL 구성이나 upstream 서버의 Cache-Control 헤더 중 더 큰 값으로 정의된다. 구체적으로 말하면 Cache-Control 헤더의 max-age 값이 사용된다. 만일 s-maxage와 max-age 모두 있는 경우, s-maxage가 선호된다. 

• upstream 이미지가 Cache-Control 헤더를 포함하지 않거나 그 값이 너무 짧은 경우 캐시 기간을 늘리기 위해서 minimumCacheTTL을 구성할 수 있다. 
• 가능한 생성 이미지 갯수를 줄이기 위해 deviceSizes와 imageSizes를 구성할 수 있다.
• 단일 이미지 형식을 위해 여러 형식을 비활성화하도록 형식을 구성할 수 있다.

 

Minimum Cache TTL

You can configure the Time to Live (TTL) in seconds for cached optimized images. In many cases, it's better to use a Static Image Import which will automatically hash the file contents and cache the image forever with a Cache-Control header of `immutable`.

캐시된 최적화 이미지에 대해 TTL(Time to Live)을 초 단위로 구성할 수 있다. 많은 경우 자동으로 파일을 해시하여 `immutable`의 `Cache-Control` 헤더로 영구히 캐시하는 Static Image Import를 사용하는 것이 더 낫다. 

module.exports = {
  images: {
    minimumCacheTTL: 60,
  },
}

If you need to add a Cache-Control header for the browser (not recommended), you can configure headers on the upstream image e.g. /some-asset.jpg not /_next/image itself.

브라우저에 Cache-Control을 추가해야 한다면 (권장되지 않음), 업스트림 이미지의 헤더를 구성할 수 있다. 예시. /_next/image 자신이 아닌 /some-asset.jpg 

 

Disable Static Imports

The default behavior allows you to import static files such as import icon from './icon.png and then pass that to the src property.

In some cases, you may wish to disable this feature if it conflicts with other plugins that expect the import to behave differently.

You can disable static image imports inside your next.config.js:

기본적인 동작은 `import icon from './icon.png'`같은 정적 파일을 가져와서 src 속성에 전달하는 것이 가능하도록 한다. 

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

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

module.exports = {
  images: {
    disableStaticImages: true,
  },
}

 

Dangerously Allow SVG

The default loader does not optimize SVG images for a few reasons. First, SVG is a vector format meaning it can be resized losslessly. Second, SVG has many of the same features as HTML/CSS, which can lead to vulnerabilities without proper Content Security Policy (CSP) headers.

If you need to serve SVG images with the default Image Optimization API, you can set dangerouslyAllowSVG and contentSecurityPolicy inside your next.config.js:

기본 로더는 몇 가지 이유로 SVG 이미지를 최적화하지 않는다. 첫 번째는, SVG는 벡터 포맷으로 손실없이 사이즈를 조절할 수 있음을 의미한다. 두 번째는, SVG에는 HTML/CSS와 동일한 기능이 많이 있는데, 적절한 컨텐츠 보안 정책(CSP) 헤더 없이는 취약점이 발생할 수 있다는 것이다. 

SVG 이미지를 기본 이미지 최적화 API로 제공하기를 원한다면, next.config.js에서 dangerouslyAllowSVG와 contentSecurityPolicy를 설정해 줄 수 있다. 

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

 

Experimental "raw" layout mode

The image component currently supports an additional `layout="raw"` mode, which renders the image without wrappers or styling. This layout mode is currently an experimental feature, while user feedback is gathered. As there is the possibility of breaking changes to the layout="raw" interface, the feature is locked behind an experimental feature flag. If you would like to use the `raw` layout mode, you must add the following to your next.config.js:

이미지 컴포넌트는 현재 추가적으로 이미지를 wrapper나 스타일링없이 렌더하는 `layout="raw"` 모드를 지원한다. 이 레이아웃 모드는 실험적인 기능으로 사용자 피드백을 모으고 있다. 그렇기 때문에 layout="raw" 인터페이스에 큰 변경사항이 있을 수 있다. 이 기능은 실험적인 기능 플래그 뒤에 잠겨있다. `raw` 레이아웃 모드를 사용하고 싶다면, 아래의 코드를 next.config.js에 추가해 주어야 한다.

module.exports = {
  experimental: {
    images: {
      layoutRaw: true,
    },
  },
}

Note on CLS with `layout="raw"`: It is possible to cause layout shift with the image component in `raw` mode. If you include a `sizes` property, the image component will not pass `height` and `width` attributes to the image, to allow you to apply your own responsive sizing. An aspect-ratio style property is automatically applied to prevent layout shift, but this won't apply on older browsers.

 `layout="raw"`의 CLS(Cumulative Layout Shift) 참고사항: `raw` 모드인 이미지 컴포넌터는 레이아웃 이동이 발생할 수 있다. `sizes` 속성을 포함시킨다면, 이미지 컴포넌트는 당신만의 반응형 사이즈를 적용시키는 것을 허용하기 위해서 `height`와 `width` 속성을 이미지에 넘겨주지 않을 것이다. 가로 세로 비율 스타일 속성은 레이아웃 이동을 방지하기 위해 자동으로 적용되지만 오래된 브라우저에서는 적용되지 않는다.

 

Animated Images

The default loader will automatically bypass Image Optimization for animated images and serve the image as-is.

Auto-detection for animated files is best-effort and supports GIF, APNG, and WebP. If you want to explicitly bypass Image Optimization for a given animated image, use the unoptimized prop.

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

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