title	description	i18nReady
이미지	Astro에서 이미지를 사용하는 방법을 알아보세요.	true

import Since from '~~/components/Since.astro'; import PackageManagerTabs from '~~/components/tabs/PackageManagerTabs.astro';

import RecipeLinks from "~/components/RecipeLinks.astro"; import { Steps } from '@astrojs/starlight/components'

Astro는 프로젝트 내부에 로컬로 저장되거나, 외부 URL에서 연결되거나, CMS 또는 CDN에서 관리되는 등 사이트에서 이미지를 사용할 수 있는 여러 가지 방법을 제공합니다!

이미지 저장 위치

`src/` vs `public/`

Astro가 이미지를 변환, 최적화, 번들링할 수 있도록 가능하면 로컬 이미지를 src/에 보관하는 것이 좋습니다. /public 디렉터리의 파일은 처리 없이 항상 있는 그대로 빌드 폴더에 제공되거나 복사됩니다.

src/에 저장된 로컬 이미지는 .astro, .md, .mdx, .mdoc 및 기타 UI 프레임워크 등 프로젝트의 모든 파일에서 사용할 수 있습니다. 이미지는 콘텐츠 근처를 포함하여 모든 폴더에 저장할 수 있습니다.

이미지 처리를 피하거나 이미지에 대한 직접 공개 링크를 갖고 싶다면 public/ 폴더에 이미지를 저장하세요.

원격 이미지

CMS (콘텐츠 관리 시스템) 또는 DAM (디지털 자산 관리) 플랫폼에 이미지를 원격으로 저장하도록 선택할 수도 있습니다.

외부 소스를 처리할 때 추가 보호를 위해 원격 이미지는 구성에 지정된 승인된 이미지 소스에서만 처리됩니다. 그러나 모든 원격 이미지는 표시될 수 있습니다.

Astro는 API를 사용하여 원격으로 데이터를 가져오거나 전체 URL 경로에서 이미지를 표시할 수 있습니다. 공통 서비스 통합의 예시는 CMS 안내서를 참조하세요.

`.astro` 파일의 이미지

.astro 파일에서 사용하려면 로컬 이미지를 파일로 가져와야 합니다. 원격 및 public/ 이미지는 가져올 필요가 없습니다.

astro:assets를 사용하여 최적화된 이미지를 위해 Astro의 내장 <Image /> 컴포넌트를 가져와 사용하세요. 또는 Astro 구문은 이미지 처리를 건너뛰는 HTML <img> 태그 직접 작성을 지원합니다.

---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="A bird sitting on a nest of eggs." />
<Image src="/images/bird-in-public-folder.jpg" alt="A bird." width="50" height="50" />
<Image src="https://example.com/remote-bird.jpg" alt="A bird." width="50" height="50" />

<img src={localBirdImage.src} alt="A bird sitting on a nest of eggs.">
<img src="/images/bird-in-public-folder.jpg" alt="A bird.">
<img src="https://example.com/remote-bird.jpg" alt="A bird.">

src/ 폴더에서 이미지를 동적으로 가져오려면 다음 레시피를 참조하세요.

`<Image />` (`astro:assets`)

내장된 <Image /> Astro 컴포넌트를 사용하여 로컬 이미지와 구성된 원격 이미지의 최적화된 버전을 표시하세요.

public/ 폴더에 있는 이미지와 프로젝트에 특별히 구성되지 않은 원격 이미지도 이미지 컴포넌트와 함께 사용할 수 있지만 처리되지는 않습니다.

<Image />는 표시된 이미지를 제어하기 위해 로컬 또는 인증된 원격 이미지의 크기, 파일 유형 및 품질을 변환할 수 있습니다. 결과 <img> 태그에는 alt, loading 및 decoding 속성이 포함되며 CLS (Cumulative Layout Shift) 를 방지하기 위해 이미지 크기를 유추합니다.

:::tip[Cumulative Layout Shift란 무엇입니까?] CLS (Cumulative Layout Shift)는 로드하는 동안 페이지에서 콘텐츠가 얼마나 이동했는지 측정하기 위한 Core Web Vital 지표입니다. <Image /> 컴포넌트는 로컬 이미지에 대해 올바른 width 및 height를 자동으로 설정하여 CLS에 맞게 최적화합니다. :::

---
// 이미지 컴포넌트와 이미지 가져오기
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // 1600x900의 이미지
---

<!-- 이미지 컴포넌트에서는 'alt'가 필수입니다. -->
<Image src={myImage} alt="A description of my image." />

<!-- 결과물 -->
<!-- 이미지가 최적화되었으며 적절한 속성이 적용되었습니다. -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="A description of my image."
/>

속성

src (필수)

이미지 파일의 src 값 형식은 이미지 파일의 위치에 따라 다릅니다.

src/의 로컬 이미지 - 상대 파일 경로를 사용하여 이미지도 가져오거나 가져오기 별칭을 구성하고 사용해야 합니다. 그런 다음 가져오기 이름을 src 값으로 사용합니다.
```
---
import { Image } from 'astro:assets';
import myImportedImage from '../assets/my-local-image.png';
---
<Image src={myImportedImage} alt="descriptive text" />
```

public/ 폴더의 이미지 - 이미지의 public 폴더에 상대적인 파일 경로 사용:

---
import { Image } from 'astro:assets';
---
<Image
  src="/images/my-public-image.png"
  alt="descriptive text"
  width="200"
  height="150"
/>

원격 이미지 - 이미지의 전체 URL을 속성 값으로 사용합니다.

---
import { Image } from 'astro:assets';
---
<Image
  src="https://example.com/remote-image.jpg"
  alt="descriptive text"
  width="200"
  height="150"
/>

alt (필수)

이미지에 대한 설명 대체 텍스트 문자열을 제공하려면 필수 alt 속성을 사용하세요.

이미지가 단지 장식용인 경우 (즉, 페이지 이해에 도움이 되지 않는 경우) alt=""를 설정하여 화면 판독기 및 기타 보조 기술이 이미지를 무시하도록 알립니다.

width 및 height (`public/`의 이미지에 필요)

이러한 속성은 이미지에 사용할 크기를 정의합니다.

이미지를 원본 가로세로 비율로 사용하는 경우 width 및 height는 선택사항입니다. 이러한 크기는 src/ 디렉터리에 있는 이미지 파일과 inferSize가 true로 설정된 원격 이미지에서 자동으로 추론될 수 있습니다.

그러나 Astro는 이러한 파일을 분석할 수 없으므로 public/ 폴더에 저장된 이미지에는 이 두 속성이 모두 필요합니다.

densities

이미지에 대해 생성할 픽셀 밀도 목록입니다.

제공된 경우 이 값은 <img> 태그에 srcset 속성을 생성하는 데 사용됩니다. 이 값을 사용할 때 widths 값을 제공하지 마세요.

이미지 크기가 커지는 것을 방지하기 위해 원본 이미지보다 더 큰 너비와 동일한 밀도는 무시됩니다.

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image 
  src={myImage} 
  width={myImage.width / 2} 
  densities={[1.5, 2]} 
  alt="A description of my image."
/>

<!-- 출력 -->
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 1.5x
    /_astro/my_image.hash.webp 2x
  "
  alt="A description of my image."
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>

widths

이미지에 대해 생성할 너비 목록입니다.

제공된 경우 이 값은 <img> 태그에 srcset 속성을 생성하는 데 사용됩니다. sizes 속성도 제공해야 합니다.

이 값을 사용할 때는 densities 값을 제공하지 마세요. 이 두 값 중 하나만 사용하여 srcset을 생성할 수 있습니다.

이미지 크기가 커지는 것을 방지하기 위해 원본 이미지보다 큰 너비는 무시됩니다.

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // 1600x900의 이미지
---
<Image
  src={myImage}
  widths={[240, 540, 720, myImage.width]}
  sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${myImage.width}px`}
  alt="A description of my image."
/>

<!-- 출력 -->
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 240w,
    /_astro/my_image.hash.webp 540w,
    /_astro/my_image.hash.webp 720w,
		/_astro/my_image.hash.webp 1600w
  "
  sizes="
    (max-width: 360px) 240px,
    (max-width: 720px) 540px,
    (max-width: 1600px) 720px,
    1600px
  "
  alt="A description of my image."
  width="1600"
  height="900"
  loading="lazy"
  decoding="async"
/>

format

선택적으로 사용할 이미지 파일 형식 출력을 명시할 수 있습니다.

기본적으로 <Image /> 컴포넌트는 .webp 파일을 생성합니다.

quality

quality는 다음 중 하나일 수 있는 선택적 속성입니다.

형식 간 자동으로 표준화되는 사전 설정 (low, mid, high, max)입니다.
0부터 100까지의 숫자 (형식에 따라 다르게 해석됨)

inferSize

원격 이미지의 원래 width 및 height를 자동으로 설정할 수 있습니다.

기본적으로 이 값은 false로 설정되어 있어 원격 이미지에 두 크기를 모두 수동으로 지정해야 합니다.

<Image /> 컴포넌트에 inferSize를 추가하거나 getImage()에 inferSize: true를 추가하여 가져올 때 이미지 콘텐츠에서 이러한 값을 추론합니다. 이는 원격 이미지의 크기를 모르거나 변경될 수 있는 경우에 유용합니다.

---
import { Image } from 'astro:assets';
---
<Image src="https://example.com/cat.png" inferSize alt="A cat sleeping in the sun." />

inferSize는 승인되지 않은 도메인의 원격 이미지의 크기를 가져올 수 있지만 이미지 자체는 처리되지 않은 상태로 유지됩니다.

추가 속성

위 속성 외에도 <Image /> 컴포넌트는 HTML <img> 태그에서 허용하는 모든 속성을 허용합니다.

예를 들어, 최종 <img> 요소에 class를 제공할 수 있습니다.

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---

<!-- 이미지 컴포넌트에서는 'alt'가 필수입니다. -->
<Image src={myImage} alt="" class="my-class" />

<!-- 출력 -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="my-class"
  alt=""
/>

기본값 설정

현재 모든 <Image /> 컴포넌트에 대한 기본값을 지정할 수 있는 방법은 없습니다. 필수 속성은 각 개별 컴포넌트에 설정되어야 합니다.

대안으로 재사용을 위해 이러한 컴포넌트를 다른 Astro 컴포넌트로 래핑할 수 있습니다. 예를 들어 블로그 게시물 이미지에 대한 컴포넌트를 만들 수 있습니다.

---
import { Image } from 'astro:assets';

const { src, ...attrs } = Astro.props;
---
<Image src={src} {...attrs} />

<style>
  img :global(img), svg {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>

`<Picture />`

다양한 형식 및 크기로 반응형 이미지를 표시하려면 내장된 <Picture /> Astro 컴포넌트를 사용하세요.

---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png'; // 1600x900의 이미지
---

<!-- Picture 컴포넌트에서는 'alt'가 필수입니다. -->
<Picture 
  src={myImage} 
  formats={['avif', 'webp']} 
  alt="A description of my image." 
/>

<!-- 출력 -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="A description of my image."
  />
</picture>

속성

<Picture />는 <Image /> 컴포넌트의 모든 속성과 함께 다음을 허용합니다.

`formats`

<source> 태그에 사용할 이미지 형식의 배열입니다. 항목은 나열된 순서대로 <source> 요소로 추가되며, 이 순서에 따라 표시되는 형식이 결정됩니다. 최상의 성능을 얻으려면 가장 최신 형식 (예: webp 또는 avif)을 먼저 나열하세요. 기본적으로 ['webp']로 설정되어 있습니다.

`fallbackFormat`

<img> 태그에 대한 대체 값으로 사용할 형식입니다.

정적 이미지의 기본값은 .png (또는 이미지가 JPG인 경우 .jpg), 애니메이션 이미지의 경우 .gif, SVG 파일의 경우 .svg입니다.

`pictureAttributes`

<picture> 태그에 추가될 속성의 객체입니다.

이 속성을 사용하여 외부 <picture> 요소 자체에 특성을 적용합니다. <Picture /> 컴포넌트에 직접 적용된 속성은 이미지 변환에 사용되는 속성을 제외하고 내부 <img> 요소에 적용됩니다.

---
import { Picture } from "astro:assets";
import myImage from "../my_image.png"; // 1600x900의 이미지
---

<Picture src={myImage} alt="A description of my image." pictureAttributes={{style: "background-color: red;"}} />

<picture style="background-color: red;">
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    alt="A description of my image."
    width="1600"
    height="900"
    loading="lazy"
    decoding="async"
  />
</picture>

`<img>`

Astro 템플릿 구문은 <img> 태그 직접 작성도 지원하며 최종 출력을 완전히 제어할 수 있습니다. 이러한 이미지는 처리 및 최적화되지 않습니다.

모든 HTML <img> 태그 속성을 허용하며 유일한 필수 속성은 src입니다.

`src/`의 로컬 이미지

로컬 이미지는 기존 .astro 파일의 상대 경로에서 가져오거나 가져오기 별칭을 구성하고 사용해야 합니다. 그런 다음 이미지의 src 및 <img> 태그에 사용할 기타 속성에 액세스할 수 있습니다.

예를 들어, CLS를 방지하고 Core Web Vitals를 개선하려면 이미지 자체의 height 및 width 속성을 사용하세요.

---
// 로컬 이미지 가져오기
import myDog from '../../images/pets/local-dog.jpg';
---
// 이미지 속성에 액세스
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="A barking dog." />

가져온 이미지 자산은 다음 시그니처와 일치합니다.

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

`public/`의 이미지

public/에 있는 이미지의 경우 src 값으로 이미지의 public 폴더에 상대적인 파일 경로를 사용합니다.

<img src="/images/public-cat.jpg" alt="A sleeping cat." >

원격 이미지

원격 이미지의 경우 이미지의 전체 URL을 src 값으로 사용하세요.

<img src="https://example.com/remote-cat.jpg" alt="A sleeping cat." >

`<Image />` vs `<img>` 선택

<Image /> 컴포넌트는 이미지를 최적화하고 CLS를 방지하기 위해 원본 가로 세로 비율을 기반으로 (로컬 이미지의) 너비와 높이를 추론합니다.

<Image /> 컴포넌트를 사용할 수 없는 경우 HTML <img> 요소를 사용하세요. 예를 들면 다음과 같습니다.

지원되지 않는 이미지 형식의 경우
Astro로 이미지 최적화를 원하지 않는 경우
클라이언트 측에서 src 속성에 동적으로 액세스하고 변경하려는 경우

원격 이미지 승인

image.domains 및 image.remotePatterns을 사용하여 이미지 최적화를 위해 인증된 이미지 소스 URL 도메인 및 패턴 목록을 구성할 수 있습니다. 이 구성은 외부 소스의 이미지를 표시할 때 사이트를 보호하기 위한 추가 안전 계층입니다.

다른 소스의 원격 이미지는 최적화되지 않지만 이러한 이미지에 <Image /> 컴포넌트를 사용하면 CLS (Cumulative Layout Shift)가 방지됩니다.

예를 들어 다음 구성에서는 astro.build의 원격 이미지만 최적화할 수 있습니다.

// astro.config.mjs
export default defineConfig({
  image: {
    domains: ["astro.build"],
  }
});

다음 구성은 HTTPS 호스트의 원격 이미지만 허용합니다.

// astro.config.mjs
export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});

CMS 또는 CDN의 이미지 사용

이미지 CDN은 모든 Astro 이미지 옵션에서 작동합니다. 이미지의 전체 URL을 <Image /> 컴포넌트, <img> 태그 또는 Markdown 표기법에서 src 속성으로 사용하세요. 원격 이미지로 이미지를 최적화하려면 승인된 도메인 또는 URL 패턴을 구성하세요.

또는 CDN이 Node.js SDK를 제공하는 경우 이를 프로젝트에서 사용할 수 있습니다. 예를 들어, Cloudinary의 SDK는 적절한 src가 포함된 <img> 태그를 생성할 수 있습니다.

Markdown 파일의 이미지

.md 파일에 표준 Markdown ![alt](src) 구문을 사용하세요. 이 구문은 Astro의 이미지 서비스 API와 함께 작동하여 src/에 저장된 로컬 이미지를 최적화합니다. 원격 이미지와 public/ 폴더에 저장된 이미지는 최적화되지 않습니다.

<!-- src/pages/post-1.md -->

# My Markdown Page

<!-- src/assets/에 저장된 로컬 이미지 -->
<!-- 상대 파일 경로 또는 가져오기 별칭 사용 -->
![A starry night sky.](../assets/stars.png)

<!-- public/images/에 저장된 이미지 -->
<!-- public/에 상대적인 파일 경로를 사용 -->
![A starry night sky.](/images/stars.png)

<!-- 다른 서버의 원격 이미지 -->
<!-- 이미지의 전체 URL을 사용 -->
![Astro](https://example.com/images/remote-image.png)

로컬 이미지에는 <img> 태그가 지원되지 않으며 .md 파일에서는 <Image /> 컴포넌트를 사용할 수 없습니다.

이미지 속성에 대한 더 많은 제어가 필요한 경우 Markdown 구문 외에 Astro의 <Image /> 컴포넌트 또는 JSX <img /> 태그를 포함할 수 있는 .mdx 파일 형식을 사용하는 것이 좋습니다. MDX 통합을 사용하여 Astro에 MDX 지원을 추가하세요.

MDX 파일의 이미지

컴포넌트와 이미지를 모두 가져와 .mdx 파일에서 Astro의 <Image /> 컴포넌트와 JSX <img /> 태그를 사용할 수 있습니다. .astro 파일에서 사용되는 것처럼 사용하십시오.

또한 가져오기가 필요 없는 표준 Markdown ![alt](src) 구문이 지원됩니다.

---
title: My Page title
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';

# My MDX Page

// 동일한 폴더에 저장된 로컬 이미지
![Houston in the wild](houston.png)

// src/assets/에 저장된 로컬 이미지
<Image src={rocket} alt="A rocketship in space." />
<img src={rocket.src} alt="A rocketship in space." />
![A rocketship in space](../assets/rocket.png)

// public/images/에 저장된 이미지
<Image src="/images/stars.png" alt="A starry night sky." />
<img src="/images/stars.png" alt="A starry night sky." />
![A starry night sky.](/images/stars.png)

// 다른 서버의 원격 이미지
<Image src="https://example.com/images/remote-image.png" />
<img src="https://example.com/images/remote-image.png" />
![Astro](https://example.com/images/remote-image.png)

콘텐츠 컬렉션의 이미지

콘텐츠 컬렉션의 이미지는 사용 중인 파일 형식에 따라 Markdown 및 MDX에서와 동일한 방식으로 처리됩니다.

또한 현재 폴더에 대한 상대 경로를 사용하여 블로그 게시물의 표지 이미지와 같은 콘텐츠 컬렉션 항목 관련 이미지를 본문에 선언할 수 있습니다.

---
title: "My first blog post"
cover: "./firstpostcover.jpeg" # "src/content/blog/firstblogcover.jpeg"로 해석됩니다.
coverAlt: "A photograph of a sunset behind a mountain range."
---

This is a blog post

콘텐츠 컬렉션 스키마의 image 도우미를 사용하면 Zod를 사용하여 이미지 메타데이터의 유효성을 검사할 수 있습니다.

import { defineCollection, z } from "astro:content";

const blogCollection = defineCollection({
	schema: ({ image }) => z.object({
		title: z.string(),
		cover: image().refine((img) => img.width >= 1080, {
			message: "Cover image must be at least 1080 pixels wide!",
		}),
		coverAlt: z.string(),
	}),
});

export const collections = {
	blog: blogCollection,
};

이미지를 가져와서 메타데이터로 변환하므로 이를 <Image/>, <img>, getImage()에 src로 전달할 수 있습니다.

아래 예시는 위 스키마에서 각 블로그 게시물의 표지 사진과 제목을 렌더링하는 블로그 인덱스 페이지를 보여줍니다.

---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const allBlogPosts = await getCollection("blog");
---

{
	allBlogPosts.map((post) => (
		<div>
			<Image src={post.data.cover} alt={post.data.coverAlt} />
			<h2>
				<a href={"/blog/" + post.slug}>{post.data.title}</a>
			</h2>
		</div>
	))
}

UI 프레임워크 컴포넌트의 이미지

UI 프레임워크 컴포넌트에 이미지를 추가할 때 프레임워크의 자체 이미지 구문을 사용하여 이미지를 렌더링합니다 (예: JSX의 <img />, Svelte의 <img>).

src와 같은 이미지 속성에 액세스하려면 로컬 이미지를 먼저 가져와야 합니다.

import stars from "../assets/stars.png";

export default function ReactImage() {
  return (
    <img src={stars.src} alt="A starry night sky." />
  )
}

<script>
  import stars from '../assets/stars.png';
</script>

<img src={stars.src} alt="A starry night sky." />

이미지 컴포넌트 전달

다른 Astro 컴포넌트와 마찬가지로 <Image /> 컴포넌트는 UI 프레임워크 컴포넌트에서 사용할 수 없습니다.

그러나 <Image />에서 생성된 정적 콘텐츠를 .astro 파일 내 프레임워크 컴포넌트에 하위 항목으로 전달하거나 명명된 <slot/>을 사용하여 전달할 수 있습니다.

---
import ReactComponent from './ReactComponent.jsx';
import { Image } from 'astro:assets';
import stars from '~/stars/docline.png';
---

<ReactComponent>
  <Image src={stars} alt="A starry night sky." />
</ReactComponent>

`getImage()`를 사용하여 이미지 생성하기

:::caution getImage()는 서버 전용 API에 의존하며 클라이언트에서 사용될 때 빌드를 중단합니다. :::

getImage() 함수는 HTML이 아닌 다른 곳 (예: API 경로)에서 사용할 이미지를 생성하기 위한 것입니다. 또한 사용자 정의 <Image /> 컴포넌트를 만들 수도 있습니다.

getImage()는 이미지 컴포넌트와 동일한 속성 (alt 제외)을 가진 옵션 객체를 사용합니다.

---
import { getImage } from "astro:assets";
import myBackground from "../background.png";

const optimizedBackground = await getImage({src: myBackground, format: 'webp'});
---

<div style={`background-image: url(${optimizedBackground.src});`}></div>

다음 속성을 가진 객체를 반환합니다.

{
  rawOptions: {...}, // 기존에 전달된 매개변수
  options: {...}, // 전달된 검증된 매개변수
  src: "...", // 생성된 이미지의 경로
  srcSet: {
    values: [...], // srcset에 대해 생성된 값, 모든 항목에는 URL과 크기 설명자가 있습니다.
    attribute: "", // values에서 생성된 srcset 속성
  }
  attributes: {...} // 이미지를 렌더링하는 데 필요한 추가 HTML 속성 (width, height, style 등)
}

대체 텍스트

모든 사용자가 동일한 방식으로 이미지를 볼 수 있는 것은 아니므로 이미지를 사용할 때 접근성은 특히 중요한 고려사항입니다. 이미지에 대한 설명 대체 텍스트를 제공하려면 alt 속성을 사용하세요.

이 속성은 <Image /> 및 <Picture /> 컴포넌트 모두에 필요합니다. 대체 텍스트가 제공되지 않으면 alt 속성을 포함하라는 유용한 오류 메시지가 제공됩니다.

이미지가 단지 장식용인 경우 (즉, 페이지 이해에 도움이 되지 않는 경우) 화면 판독기가 이미지를 무시할 수 있도록 alt=""를 설정하세요.

기본 이미지 서비스

Sharp는 astro:assets에 사용되는 기본 이미지 서비스입니다. image.service 옵션을 사용하여 이미지 서비스를 추가로 구성할 수 있습니다.

:::note pnpm과 같은 엄격한 패키지 관리자를 사용하는 경우 Astro 종속성임에도 불구하고 Sharp를 프로젝트에 수동으로 설치해야 할 수 있습니다.

pnpm add sharp

:::

Squoosh 구성

Squoosh를 사용하여 이미지를 변환하려면 다음과 같이 구성을 업데이트하세요.

import { defineConfig, squooshImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: squooshImageService(),
  },
});

무작동 패스스루 서비스 구성

server 또는 hybrid 모드용 어댑터가 Astro의 내장 Squoosh 및 Sharp 이미지 최적화를 지원하지 않는 경우 (예: Deno, Cloudflare) <Image /> 및 <Picture /> 컴포넌트를 사용할 수 있도록 무작동 이미지 서비스를 구성할 수 있습니다. Astro는 이러한 환경에서 이미지 변환 및 처리를 수행하지 않습니다. 그러나 CLS (Cumulative Layout Shift) 없음, 강제된 alt 속성 및 일관된 작성 환경을 포함하여 astro:assets 사용의 다른 이점을 계속 누릴 수 있습니다.

Squoosh 및 Sharp 이미지 처리를 모두 방지하려면 passthroughImageService()를 구성하세요.

import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});

커뮤니티 통합

Astro 프로젝트의 이미지를 최적화하고 작업하기 위한 여러 타사 커뮤니티 이미지 통합이 있습니다.

v2.x에서 v3.0으로 업그레이드

astro:assets는 더 이상 Astro v3.0의 실험적 플래그 뒤에 있지 않습니다.

<Image />는 이제 내장 컴포넌트이며 이전 @astrojs/image 통합은 제거되었습니다.

Astro에서 이미지 사용에 대한 이러한 변경 사항 및 기타 수반되는 변경 사항은 Astro 프로젝트를 이전 버전에서 업그레이드할 때 일부 주요 변경 사항을 초래할 수 있습니다.

Astro v2.x 프로젝트를 v3.0으로 업그레이드하려면 아래 지침을 적절하게 따르세요.

`experimental.assets`에서 업그레이드

이전에 astro:assets에 대한 실험적 플래그를 활성화한 경우 이제 기본적으로 자산 기능이 포함된 Astro v3.0용으로 프로젝트를 업데이트해야 합니다.

`experimental.assets` 플래그 제거

실험적 플래그를 제거합니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    assets: true
  }
});

필요한 경우 astro/client-image 참조를 astro/client로 바꾸도록 src/env.d.ts 파일도 업데이트하세요.

/// <reference types="astro/client-image" />
/// <reference types="astro/client" />

`~/assets` 가져오기 별칭 제거

이 가져오기 별칭은 더 이상 astro:assets에 기본적으로 포함되지 않습니다. 실험적 자산과 함께 이 별칭을 사용하는 경우 이를 상대 파일 경로로 변환하거나 자신만의 가져오기 별칭을 생성해야 합니다.

---
import rocket from '~/assets/rocket.png';
import rocket from '../../assets/rocket.png';
---

Cloudflare, Deno, Vercel Edge, Netlify Edge에 대한 간단한 자산 지원 추가

Astro v3.0을 사용하면 Astro의 기본 제공 Squoosh 및 Sharp 이미지 최적화를 지원하지 않는 Cloudflare, Deno, Vercel Edge, Netlify Edge에서 astro:assets가 오류 없이 작동할 수 있습니다. Astro는 이러한 환경에서 이미지 변환 및 처리를 수행하지 않습니다. 그러나 CLS (Cumulative Layout Shift) 없음, 강제된 alt 속성 및 일관된 작성 환경을 포함하여 astro:assets 사용의 다른 이점을 계속 누릴 수 있습니다.

이전에는 이러한 제약으로 인해 astro:assets 사용을 피했다면 이제 문제 없이 사용할 수 있습니다. 이 동작을 명시적으로 선택하도록 무작동 이미지 서비스를 구성할 수 있습니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  image: {
    service: {
      entrypoint: 'astro/assets/services/noop'
    }
  }
});

이미지를 저장할 위치 결정

이미지를 저장할 위치를 결정하는 데 도움이 되는 이미지 안내서를 참조하세요. astro:assets가 제공하는 유연성을 추가하여 이미지를 저장하는 새로운 옵션을 활용하고 싶을 수도 있습니다. 예를 들어, 이제 표준 Markdown ![alt](src) 구문을 사용하여 src/ 프로젝트의 상대 이미지를 Markdown, MDX, Markdoc에서 참조할 수 있습니다.

기존 `<img>` 태그 업데이트

이전에는 이미지를 가져오면 이미지 경로가 포함된 간단한 string이 반환되었습니다. 이제 가져온 이미지 자산은 다음 시그니처와 일치합니다.

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

기존 <img> 태그 (UI 프레임워크 컴포넌트의 이미지 포함)의 src 속성을 업데이트해야 하며 가져온 이미지에서 현재 사용할 수 있는 다른 속성도 업데이트할 수도 있습니다.

---
import rocket from '../images/rocket.svg';
---
<img src={rocket} width="250" height="250" alt="A rocketship in space." />

<img src={rocket.src} width={rocket.width} height={rocket.height} alt="A rocketship in space." />

Markdown, MDX, Markdoc 파일 업데이트

이제 프로젝트 src/의 상대 이미지를 표준 Markdown ![alt](src) 구문을 사용하여 Markdown, MDX, Markdoc에서 참조할 수 있습니다.

이를 통해 이미지를 public/ 디렉터리에서 프로젝트 src/로 이동하여 처리 및 최적화할 수 있습니다. public/에 있는 기존 이미지와 원격 이미지는 여전히 유효하지만 Astro의 빌드 프로세스에 의해 최적화되지 않습니다.

# My Markdown Page

<!-- 이제 로컬 이미지가 가능해졌습니다! -->
![A starry night sky.](../../images/stars.png)

<!-- 콘텐츠 옆에 이미지를 보관하세요! -->
![A starry night sky.](./stars.png)

이미지 속성에 대한 더 많은 제어가 필요한 경우 Markdown 구문 외에 Astro의 <Image /> 컴포넌트 또는 JSX <img /> 태그를 포함할 수 있는 .mdx 파일 형식을 사용하는 것이 좋습니다. MDX 통합을 사용하여 Astro에 MDX 지원을 추가하세요.

`@astrojs/image` 제거

Astro v2.x에서 이미지 통합을 사용하는 경우 다음 단계를 완료하세요.

1. `@astrojs/image` 통합을 제거합니다.

통합을 제거한 다음 `astro.config.mjs` 파일에서도 [통합을 제거](/ko/guides/integrations-guide/#통합-제거)해야 합니다.

```js del={3,7}
// astro.config.mjs
import { defineConfig } from 'astro/config';
import image from '@astrojs/image';

export default defineConfig({
  integrations: [
    image(),
  ]
})
```

타입을 업데이트합니다 (필요한 경우).

 `src/env.d.ts`에 `@astrojs/image`에 대해 구성된 특수 유형이 있는 경우, v3으로 업그레이드해도 이 단계가 완료되지 않으면 이를 기본 Astro 타입으로 다시 변경해야 할 수 있습니다.

 ```ts title="src/env.d.ts" del={1} ins={2}
  /// <reference types="@astrojs/image/client" />
  /// <reference types="astro/client" />
 ```

 마찬가지로 필요한 경우 `tsconfig.json`을 업데이트합니다.

 ```json title="tsconfig.json" del={3} ins={4}
 {
 	"compilerOptions": {
 	  "types": ["@astrojs/image/client"]
 	  "types": ["astro/client"]
 	}
 }
 ```

기존 <Image /> 컴포넌트를 마이그레이션합니다.

새로운 내장 <Image /> 컴포넌트를 사용하려면 모든 import 문을 @astrojs/image/components에서 astro:assets로 변경하세요.

현재 지원되는 이미지 자산 속성이 아닌 컴포넌트 속성을 제거하세요.

예를 들어, aspectRatio는 이제 width 및 height 속성에서 자동으로 추론되므로 더 이상 지원되지 않습니다.
```
---
import { Image } from '@astrojs/image/components';
import { Image } from 'astro:assets';
import localImage from '../assets/logo.png';
const localAlt = 'The Astro Logo';
---

<Image
  src={localImage}
  width={300}
  aspectRatio="16:9"
  alt={localAlt}
/>
```
기본 이미지 서비스를 선택합니다.

Sharp는 이제 astro:assets에 사용되는 기본 이미지 서비스입니다. Sharp를 사용하려면 구성이 필요하지 않습니다.

Squoosh를 사용하여 이미지를 변환하려면 다음 image.service 옵션으로 구성을 업데이트하세요.
```
import { defineConfig, squooshImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: squooshImageService(),
  },
});
```

콘텐츠 컬렉션 스키마 업데이트

이제 현재 폴더에 대한 상대 경로를 사용하여 블로그 게시물의 표지 이미지와 같은 콘텐츠 컬렉션 항목에 대한 관련 이미지를 프런트매터에서 선언할 수 있습니다.

콘텐츠 컬렉션을 위한 새로운 image 도우미를 사용하면 Zod를 사용하여 이미지 메타데이터의 유효성을 검사할 수 있습니다. 콘텐츠 컬렉션에서 이미지를 사용하는 방법에 대해 자세히 알아보세요.

Astro v3.0에서 이미지 가져오기 탐색

Astro v3.0에서는 이미지에 대한 이전 가져오기 동작을 유지해야 하고 이미지 URL의 문자열 표현이 필요한 경우 이미지를 가져올 때 이미지 경로 끝에 ?url을 추가하세요. 예를 들어:

---
import Sprite from '../assets/logo.svg?url';
---
<svg>
  <use xlink:href={Sprite + '#cart'} />
</svg>

이 접근 방식을 사용하면 URL 문자열을 얻을 수 있습니다. 개발 중에는 Astro가 src/ 경로를 사용하지만 빌드 시 /_astro/cat.a6737dd3.png와 같은 해시된 경로를 생성한다는 점을 명심하세요.

이미지 객체 자체로 직접 작업하려는 경우 .src 속성에 액세스할 수 있습니다. 이 접근 방식은 Core Web Vitals 측정항목의 이미지 크기 관리 및 CLS 방지와 같은 작업에 가장 적합합니다.

새로운 가져오기 동작으로 전환하는 경우 ?url과 .src 메서드를 결합하는 것이 원활한 이미지 처리를 위한 올바른 방법일 수 있습니다.

Files

images.mdx

Latest commit

History

images.mdx

File metadata and controls

이미지 저장 위치

src/ vs public/

원격 이미지

.astro 파일의 이미지

<Image /> (astro:assets)

속성

src (필수)

alt (필수)

width 및 height (public/의 이미지에 필요)

densities

widths

format

quality

inferSize

추가 속성

기본값 설정

<Picture />

속성

formats

fallbackFormat

pictureAttributes

<img>

src/의 로컬 이미지

public/의 이미지

원격 이미지

<Image /> vs <img> 선택

원격 이미지 승인

CMS 또는 CDN의 이미지 사용

Markdown 파일의 이미지

MDX 파일의 이미지

콘텐츠 컬렉션의 이미지

UI 프레임워크 컴포넌트의 이미지

이미지 컴포넌트 전달

getImage()를 사용하여 이미지 생성하기

대체 텍스트

기본 이미지 서비스

Squoosh 구성

무작동 패스스루 서비스 구성

커뮤니티 통합

v2.x에서 v3.0으로 업그레이드

experimental.assets에서 업그레이드

experimental.assets 플래그 제거

~/assets 가져오기 별칭 제거

Cloudflare, Deno, Vercel Edge, Netlify Edge에 대한 간단한 자산 지원 추가

이미지를 저장할 위치 결정

기존 <img> 태그 업데이트

Markdown, MDX, Markdoc 파일 업데이트

@astrojs/image 제거

콘텐츠 컬렉션 스키마 업데이트

Astro v3.0에서 이미지 가져오기 탐색

`src/` vs `public/`

`.astro` 파일의 이미지

`<Image />` (`astro:assets`)

width 및 height (`public/`의 이미지에 필요)

`<Picture />`

`formats`

`fallbackFormat`

`pictureAttributes`

`<img>`

`src/`의 로컬 이미지

`public/`의 이미지

`<Image />` vs `<img>` 선택

`getImage()`를 사용하여 이미지 생성하기

`experimental.assets`에서 업그레이드

`experimental.assets` 플래그 제거

`~/assets` 가져오기 별칭 제거

기존 `<img>` 태그 업데이트

`@astrojs/image` 제거