컨텐츠로 건너뛰기

이미지

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

이미지 저장 위치

섹션 제목: 이미지 저장 위치

src/ vs public/

섹션 제목: src/ vs public/

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

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

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

원격 이미지

섹션 제목: 원격 이미지

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

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

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

.astro 파일의 이미지

섹션 제목: .astro 파일의 이미지

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

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

src/pages/blog/my-images.astro
---
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)

섹션 제목: &lt;Image /&gt; (astro:assets)

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

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

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

src/components/MyComponent.astro
---
// 이미지 컴포넌트와 이미지 가져오기
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/의 로컬 이미지 - 상대 파일 경로를 사용하여 이미지도 가져오거나 가져오기 별칭을 구성하고 사용해야 합니다. 그런 다음 가져오기 이름을 src 값으로 사용합니다.

    src/pages/index.astro
    ---
    import { Image } from 'astro:assets';
    import myImportedImage from '../assets/my-local-image.png';
    ---
    <Image src={myImportedImage} alt="descriptive text" />

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

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

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

    src/pages/index.astro
    ---
    import { Image } from 'astro:assets';
    ---
    <Image
      src="https://example.com/remote-image.jpg"
      alt="descriptive text"
      width="200"
      height="150"
    />
alt (필수)
섹션 제목: alt (필수)

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

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

width 및 height (public/의 이미지에 필요)
섹션 제목: width 및 height (public/의 이미지에 필요)

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

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

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

densities
섹션 제목: densities

Added in: astro@3.3.0

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

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

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

src/components/MyComponent.astro
---
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
섹션 제목: widths

Added in: astro@3.3.0

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

제공된 경우 이 값은 <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
섹션 제목: format

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

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

quality
섹션 제목: quality

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

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

Added in: astro@4.4.0

원격 이미지의 원래 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를 제공할 수 있습니다.

src/pages/index.astro
---
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 컴포넌트로 래핑할 수 있습니다. 예를 들어 블로그 게시물 이미지에 대한 컴포넌트를 만들 수 있습니다.

src/components/BlogPostImage.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 />

섹션 제목: &lt;Picture /&gt;

Added in: astro@3.3.0

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

src/pages/index.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
섹션 제목: formats

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

fallbackFormat
섹션 제목: fallbackFormat

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

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

pictureAttributes
섹션 제목: pictureAttributes

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

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

src/components/MyComponent.astro
---
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>

섹션 제목: &lt;img&gt;

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

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

src/의 로컬 이미지

섹션 제목: src/의 로컬 이미지

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

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

src/pages/posts/post-1.astro
---
// 로컬 이미지 가져오기
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/의 이미지

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> 선택

섹션 제목: &lt;Image /&gt; vs &lt;img&gt; 선택

<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의 이미지 사용

섹션 제목: CMS 또는 CDN의 이미지 사용

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

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

Markdown 파일의 이미지

섹션 제목: Markdown 파일의 이미지

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

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 파일의 이미지

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

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

src/pages/post-1.mdx
---
title: My Page title
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';


# My MDX Page


// 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에서와 동일한 방식으로 처리됩니다.

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

src/content/blog/my-post.md
---
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를 사용하여 이미지 메타데이터의 유효성을 검사할 수 있습니다.

src/content/config.ts
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로 전달할 수 있습니다.

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

src/pages/blog.astro
---
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 프레임워크 컴포넌트의 이미지

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

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

src/components/ReactImage.jsx
import stars from "../assets/stars.png";


export default function ReactImage() {
  return (
    <img src={stars.src} alt="A starry night sky." />
  )
}
src/components/SvelteImage.svelte
<script>
  import stars from '../assets/stars.png';
</script>


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

이미지 컴포넌트 전달

섹션 제목: 이미지 컴포넌트 전달

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

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

ImageWrapper.astro
---
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()를 사용하여 이미지 생성하기

섹션 제목: getImage()를 사용하여 이미지 생성하기

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 옵션을 사용하여 이미지 서비스를 추가로 구성할 수 있습니다.

Squoosh 구성

섹션 제목: Squoosh 구성

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

astro.config.mjs
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()를 구성하세요.

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


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

커뮤니티 통합

섹션 제목: 커뮤니티 통합

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

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

섹션 제목: v2.x에서 v3.0으로 업그레이드

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

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

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

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

experimental.assets에서 업그레이드

섹션 제목: experimental.assets에서 업그레이드

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

experimental.assets 플래그 제거

섹션 제목: experimental.assets 플래그 제거

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

astro.config.mjs
import { defineConfig } from 'astro/config';


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

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

src/env.d.ts
/// <reference types="astro/client-image" />
/// <reference types="astro/client" />

~/assets 가져오기 별칭 제거

섹션 제목: ~/assets 가져오기 별칭 제거

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

src/pages/posts/post-1.astro
---
import rocket from '~/assets/rocket.png';
import rocket from '../../assets/rocket.png';
---

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

섹션 제목: 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 사용을 피했다면 이제 문제 없이 사용할 수 있습니다. 이 동작을 명시적으로 선택하도록 무작동 이미지 서비스를 구성할 수 있습니다.

astro.config.mjs
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> 태그 업데이트

섹션 제목: 기존 &lt;img&gt; 태그 업데이트

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

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

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

src/components/MyComponent.astro
---
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 파일 업데이트

섹션 제목: Markdown, MDX, Markdoc 파일 업데이트

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

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

src/pages/posts/post-1.md
# 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 제거

섹션 제목: @astrojs/image 제거

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

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

    통합을 제거한 다음 astro.config.mjs 파일에서도 통합을 제거해야 합니다.

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import image from '@astrojs/image';
    

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

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

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

    src/env.d.ts
     /// <reference types="@astrojs/image/client" />
     /// <reference types="astro/client" />

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

    tsconfig.json
    {
      "compilerOptions": {
        "types": ["@astrojs/image/client"]
        "types": ["astro/client"]
      }
    }

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

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

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

    예를 들어, aspectRatio는 이제 width 및 height 속성에서 자동으로 추론되므로 더 이상 지원되지 않습니다.

    src/components/MyComponent.astro
    ---
    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}
    />

  4. 기본 이미지 서비스를 선택합니다.

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

    Squoosh를 사용하여 이미지를 변환하려면 다음 image.service 옵션으로 구성을 업데이트하세요.

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

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

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

섹션 제목: 콘텐츠 컬렉션 스키마 업데이트

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

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

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

섹션 제목: Astro v3.0에서 이미지 가져오기 탐색

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

src/pages/blog/MyImages.astro
---
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 메서드를 결합하는 것이 원활한 이미지 처리를 위한 올바른 방법일 수 있습니다.