컨텐츠로 건너뛰기

이미지

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/에 저장된 로컬 이미지를 최적화합니다. 원격 이미지와 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 파일의 이미지

컴포넌트와 이미지를 모두 가져와 .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


// 동일한 폴더에 저장된 로컬 이미지
![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에서와 동일한 방식으로 처리됩니다.

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

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 프로젝트의 이미지를 최적화하고 작업하기 위한 여러 타사 커뮤니티 이미지 통합이 있습니다.