이미지

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

Astro는 이미지를 최적화하거나 변환하기 위해 Image 및 Picture 컴포넌트, Markdown 이미지 구문 처리, SVG 컴포넌트, 이미지 생성 함수를 제공합니다. 또한 기본적으로 반응형 이미지의 크기를 자동으로 조정하도록 구성하거나 개별 Image 및 Picutre 컴포넌트에 반응형 속성을 설정할 수 있습니다.

.astro 또는 Markdown 파일에서 기본 HTML 요소를 사용하거나, 파일 형식의 표준 방식 (예: MDX 및 JSX의 <img />)으로 이미지 및 SVG 파일을 사용할 수 있습니다. 하지만 Astro는 이러한 이미지에 대해 어떠한 처리나 최적화도 수행하지 않습니다.

<Image /> 및 <Picture /> 컴포넌트의 전체 API 참조를 확인하세요.

이미지 저장 위치

`src/` vs `public/`

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

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

이미지 처리를 피하려면 public/ 폴더에 이미지를 저장하세요. 이러한 이미지는 프로젝트 파일에서 도메인의 URL 경로로 사용할 수 있으며 직접 공개 링크를 가질 수 있습니다. 예를 들어 사이트의 파비콘은 일반적으로 브라우저에서 식별할 수 있는 이 폴더의 루트에 배치됩니다.

원격 이미지

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

Astro는 API를 사용하여 원격으로 데이터를 가져오거나 전체 URL 경로를 이용하여 이미지를 표시할 수 있습니다.

외부 소스를 다룰 때 추가적인 보호를 위해 Astro의 이미지 컴포넌트와 도우미 함수는 구성에서 지정한 승인된 이미지 소스의 이미지만 처리 (예: 최적화, 변환)합니다. 다른 소스의 원격 이미지는 처리하지 않고 표시됩니다.

`.astro` 파일의 이미지

옵션: <Image />, <Picture />, <img>, <svg>, SVG 컴포넌트

Astro의 템플릿 언어를 사용하면 <Image /> 컴포넌트를 통해 최적화된 이미지를 렌더링할 수 있으며, <Picture /> 컴포넌트를 통해 여러 크기와 형식의 이미지를 생성할 수 있습니다. 두 컴포넌트 모두 컨테이너 크기에 따라 이미지의 크기를 조정하고 기기의 화면 크기와 해상도에 반응하는 반응형 이미지 속성을 허용합니다.

또한, .astro 컴포넌트에서 SVG 파일을 Astro 컴포넌트로 가져와 사용할 수 있습니다.

<img> 및 <svg>를 포함한 모든 네이티브 HTML 태그는 .astro 컴포넌트에서 사용할 수 있습니다. HTML 태그를 통해 렌더링된 이미지는 처리되지 않은 상태 (예: 최적화, 변환 등) 그대로 빌드 폴더에 복사됩니다.

.astro 파일의 모든 이미지의 src 속성의 값은 이미지 파일의 위치에 의해 결정됩니다.

프로젝트 src/ 폴더의 로컬 이미지는 파일의 상대 경로에서 가져오기를 사용합니다.

Image 및 Picture 컴포넌트는 명명된 가져오기를 직접 사용하지만 (예: src={rocket}), <img> 태그는 가져오기의 src 객체 속성을 사용합니다. (예: src={rocket.src})
원격 및 public/ 이미지는 URL 경로를 사용합니다.

원격 이미지의 경우, 전체 URL을 제공합니다. (예: src="https://www.example.com/images/my-remote-image.jpg") 파일이 public/ 폴더에 있는 경우, 파일의 위치에 해당하는 사이트의 상대 URL 경로를 제공합니다. (예: 이미지의 위치가 public/images/my-public-image.jpg인 경우, src="/images/my-public-image.jpg")

---
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.">

<Image /> 및 <Picture /> 컴포넌트의 필수 및 선택적 속성을 모두 포함한 전체 API 참조를 확인하세요.

관련 레시피: 동적으로 이미지 가져오기

Markdown 파일의 이미지

옵션: ![](), <img> (공개 및 원격 이미지)

.md 파일에 표준 Markdown ![alt](src) 구문을 사용하세요. src/에 저장된 로컬 이미지와 원격 이미지는 처리 및 최적화됩니다. 전역 반응형 이미지를 구성하면 이러한 이미지도 반응형 이미지가 됩니다.

public/ 폴더에 저장된 이미지는 최적화되지 않습니다.

# Markdown 페이지

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

<!-- public/images/에 저장된 이미지 -->
<!-- public/의 상대 파일 경로 사용 -->
![별이 빛나는 밤하늘](/images/stars.png)

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

HTML <img> 태그는 public/에 저장된 이미지 또는 원격 이미지를 최적화나 처리 없이 표시하는 데 사용할 수도 있습니다. 하지만 <img>는 src의 로컬 이미지를 지원하지 않습니다.

<Image /> 및 <Picture /> 컴포넌트는 .md 파일에서 사용할 수 없습니다. 이미지 속성을 보다 세밀하게 제어해야 하는 경우, Astro의 MDX 통합을 사용하여 .mdx 파일 형식 지원을 추가하는 것을 권장합니다. MDX는 컴포넌트와 Markdown 구문의 결합과 MDX의 이미지 옵션을 사용할 수 있도록 기능을 추가합니다.

MDX 파일의 이미지

옵션: <Image />, <Picture />, <img />, ![](), SVG 컴포넌트

.mdx 파일에서 이미지와 Astro의 <Image /> 및 <Picture /> 컴포넌트를 모두 가져와 사용할 수 있습니다. .astro 파일에서 사용하는 것처럼 사용하면 됩니다. JSX의 <img /> 태그는 처리되지 않은 이미지도 지원하며 HTML의 <img> 태그와 동일한 이미지 가져오기를 사용합니다.

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

---
title: 페이지 제목
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';

# MDX 페이지

// 동일한 폴더에 저장된 로컬 이미지
![야생의 휴스턴](houston.png)

// src/assets/에 저장된 로컬 이미지
<Image src={rocket} alt="우주에 떠 있는 로켓선" />
<img src={rocket.src} alt="우주에 떠 있는 로켓선" />
![우주에 떠 있는 로켓선](../assets/rocket.png)

// public/images/에 저장된 이미지
<Image src="/images/stars.png" alt="별이 빛나는 밤하늘" />
<img src="/images/stars.png" alt="별이 빛나는 밤하늘" />
![별이 빛나는 밤하늘](/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)

<Image /> 및 <Picture /> 컴포넌트의 전체 API 참조를 확인하세요.

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

이미지 옵션: 프레임워크 자체 이미지 구문 (예: JSX의 <img />, Svelte의 <img>)

src와 같은 이미지 속성에 접근하기 위해 로컬 이미지를 먼저 가져와야 합니다. 그러면 프레임워크의 자체 이미지 구문을 사용하여 이미지를 렌더링할 수 있습니다.

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

export default function ReactImage() {
  return (
    <img src={stars.src} alt="별이 빛나는 밤하늘" />
  )
}

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

<img src={stars.src} alt="별이 빛나는 밤하늘" />

클라이언트 아일랜드는 프레임워크 자신의 유효한 코드를 포함해야 하므로, UI 프레임워크 컴포넌트에서 Astro 컴포넌트 (예: <Image />, <Picture />, SVG 컴포넌트)를 사용할 수 없습니다.

하지만, 이러한 컴포넌트에서 생성된 정적 콘텐츠를 .astro 파일 내부에 있는 프레임워크 컴포넌트에 자식으로 전달하거나 명명된 <slot/>을 사용하여 전달할 수 있습니다.

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

<ReactComponent>
  <Image src={stars} alt="별이 빛나는 밤하늘" />
</ReactComponent>

Astro 컴포넌트의 이미지

Astro는 이미지를 위한 두 가지 내장 컴포넌트 (<Image /> 및 <Picture />)를 제공하며, SVG 파일을 가져와 Astro 컴포넌트로 사용할 수도 있습니다. 이러한 컴포넌트는 .astro 컴포넌트를 가져와 렌더링할 수 있는 모든 파일에서 사용할 수 있습니다.

`<Image />`

기본으로 제공되는 <Image /> Astro 컴포넌트를 사용하여 다음의 최적화된 버전을 표시합니다.

src/ 폴더에 있는 로컬 이미지
인증된 소스에서 가져오는 구성된 원격 이미지

<Image />는 표시된 이미지를 제어하기 위해 로컬 또는 인증된 원격 이미지의 크기, 파일 유형 및 품질을 변환할 수 있습니다. 이 변환은 사전 렌더링된 페이지의 빌드 시 발생합니다. 페이지가 요청 시 렌더링될 때 이 변환은 페이지가 보여질 때 즉시 발생합니다. 결과 <img> 태그에는 alt, loading 및 decoding 속성이 포함되며 CLS (Cumulative Layout Shift)를 방지하기 위해 이미지 크기를 유추합니다.

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

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

<!-- 사전 렌더링된 출력 -->
<!-- 이미지가 최적화되었으며 적절한 속성이 적용되었습니다. -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="이미지 설명"
/>

<!-- 요청 시 렌더링되는 출력 -->
<!-- src는 요청 시 생성된 엔드포인트를 사용합니다. -->
<img
  src="/_image?href=%2F_astro%2Fmy_image.hash.webp&amp;w=1600&amp;h=900&amp;f=webp"
  <!-- ... -->
/>

<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=""
/>

`<Picture />`

추가된 버전: astro@3.3.0

Astro의 내장 <Picture /> 컴포넌트를 사용하여 이미지의 여러 형식 및/또는 크기가 포함된 <picture> 태그를 생성할 수 있습니다. 이를 통해 표시할 기본 파일 형식을 지정하면서, 대체 형식을 제공할 수 있습니다. <Image /> 컴포넌트와 마찬가지로 미리 렌더링된 페이지에서는 이미지가 빌드 시 처리됩니다. 페이지가 요청 시 렌더링되는 경우에는 페이지가 표시될 때 즉시 처리됩니다.

다음은 <Picture /> 컴포넌트를 사용하여 로컬 .png 파일을 웹 친화적인 avif 및 webp 형식과 필요 시 대체로 표시할 수 있는 .png <img>로 변환하는 예시입니다.

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

<!-- Picture 컴포넌트에서는 'alt'가 필수입니다. -->
<Picture
  src={myImage}
  formats={['avif', 'webp']}
  alt="이미지 설명"
/>

<!-- 사전 렌더링된 출력 -->
<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="이미지 설명"
  />
</picture>

<Picture /> 컴포넌트의 속성에 대한 자세한 내용은 astro:assets 참조에서 알아보세요.

반응형 이미지 동작

추가된 버전: astro@5.10.0 새로운 기능

반응형 이미지는 다양한 기기에서 성능을 개선하기 위해 조정되는 이미지입니다. 이러한 이미지는 컨테이너에 맞게 크기가 조정될 수 있으며 방문자의 화면 크기와 해상도에 따라 다양한 크기로 제공될 수 있습니다.

<Image /> 또는 <Picture /> 컴포넌트에 반응형 이미지 속성을 적용하면 Astro는 이미지에 필요한 srcset 및 sizes 값을 생성하고 필요한 스타일을 적용하여 이미지 크기가 올바르게 조정되도록 합니다.

이 반응형 동작이 전역적으로 구성되면 모든 이미지 컴포넌트와 Markdown의 ![]() 구문을 사용하는 모든 로컬 및 원격 이미지에 적용됩니다.

public/ 폴더에 있는 이미지는 최적화되지 않으며 반응형 이미지도 지원되지 않습니다.

MDN 웹 문서에서 반응형 이미지에 대해 자세히 알아보세요.

생성된 반응형 이미지 HTML 출력

레이아웃이 기본적으로 또는 개별 컴포넌트에 설정되면, 이미지의 크기와 레이아웃 유형에 따라 이미지에 srcset 및 sizes 속성이 자동으로 생성됩니다. constrained 및 full-width 레이아웃을 사용하는 이미지에는 컨테이너에 따라 크기를 조정하기 위한 스타일이 적용됩니다.

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="이미지 설명" layout='constrained' width={800} height={600} />

이 <Image /> 컴포넌트는 미리 렌더링된 페이지에 다음과 같은 HTML 출력을 생성합니다.

<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
      /_astro/my_image.hash2.webp 750w,
      /_astro/my_image.hash3.webp 800w,
      /_astro/my_image.hash4.webp 828w,
      /_astro/my_image.hash5.webp 1080w,
      /_astro/my_image.hash6.webp 1280w,
      /_astro/my_image.hash7.webp 1600w"
  alt="이미지 설명"
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>

반응형 이미지 스타일

image.responsiveStyles: true를 설정하면 이미지 크기가 올바르게 조정되도록 몇 가지 전역 스타일을 적용합니다. 대부분의 경우 이 구성을 기본적으로 활성화하는게 좋습니다. 추가 스타일이 없으면 이미지가 반응형으로 동작하지 않습니다.

하지만 반응형 이미지 스타일을 직접 처리하고 싶거나, Tailwind 4를 사용할 때 이러한 기본값을 재정의해야 하는 경우에는 기본값인 false를 유지하세요.

Astro에 적용되는 전역 스타일은 레이아웃 유형에 따라 달라지며, 생성된 srcset 및 sizes 속성에 가장 적합한 결과를 생성하도록 설계되었습니다. 기본 스타일은 다음과 같습니다.

:where([data-astro-image]) {
  object-fit: var(--fit);
  object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
  width: 100%;
}
:where([data-astro-image='constrained']) {
  max-width: 100%;
}

스타일은 특이도가 0인 :where() 의사 클래스를 사용하므로 고유한 스타일로 쉽게 재정의할 수 있습니다. 모든 CSS 선택자는 :where()보다 특이도가 높으므로 이미지에 고유 스타일을 추가하여 스타일을 쉽게 재정의할 수 있습니다.

<Image /> 또는 <Picture /> 컴포넌트에서 fit과 position props를 설정하여 이미지별로 object-fit 및 object-position 스타일을 재정의할 수 있습니다.

Tailwind 4와 반응형 이미지

Tailwind 4는 Astro의 기본 반응형 스타일과 호환됩니다. 그러나 Tailwind는 캐스케이드 레이어를 사용하므로 이 규칙은 항상 레이어를 사용하지 않는 규칙보다 특이성이 낮으며, 여기에는 Astro의 반응형 스타일도 포함됩니다. 따라서 Astro의 스타일링이 Tailwind 스타일링보다 우선합니다. Astro의 기본 스타일링 대신 Tailwind 규칙을 사용하려면 Astro의 기본 반응형 스타일을 비활성화 하세요.

SVG 컴포넌트

추가된 버전: astro@5.7.0

Astro를 사용하면 SVG 파일을 가져와서 Astro 컴포넌트처럼 사용할 수 있습니다. Astro는 SVG의 콘텐츠를 HTML 출력에 인라인으로 삽입합니다.

로컬 .svg 파일의 기본 가져오기를 참조하세요. 이 가져오기는 Astro 컴포넌트로 처리되므로, 동적 태그를 사용할 때와 동일한 규칙 (예: 대문자 사용)을 따라야 합니다.

---
import Logo from './path/to/svg/file.svg';
---

<Logo />

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

SVG 컴포넌트 속성

width, height, fill, stroke와 같은 props와 기본 <svg> 요소에서 허용하는 다른 모든 속성을 전달할 수 있습니다. 이러한 속성은 자동으로 내부 <svg> 요소에 적용됩니다. 원본 .svg 파일에 속성이 있지만, 속성이 컴포넌트에 전달되면, 컴포넌트에 전달된 값이 원본 값을 덮어씁니다.

---
import Logo from '../assets/logo.svg';
---

<Logo width={64} height={64} fill="currentColor" />

사용자 정의 이미지 컴포넌트 만들기

<Image /> 또는 <Picture/> 컴포넌트를 다른 Astro 컴포넌트로 래핑하여 재사용 가능한 사용자 정의 이미지 컴포넌트를 만들 수 있습니다. 이렇게 하면 기본 속성과 스타일을 한 번만 설정할 수 있습니다.

예를 들어, props로 속성을 받아 각 이미지에 일관된 스타일을 적용하는 블로그 게시물 이미지용 컴포넌트를 만들 수 있습니다.

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

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

<style>
  img {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>

HTML의 `<img>` 태그를 사용하여 처리되지 않은 이미지 표시

Astro 템플릿 구문은 최종 출력에 대한 완전한 제어를 위해 <img> 태그를 직접 작성하는 것도 지원합니다. 이러한 이미지는 처리 및 최적화되지 않습니다. 모든 HTML <img> 태그 속성을 허용하며, 필수 속성은 src뿐입니다. 그러나 접근성을 위한 alt 속성을 포함할 것을 강력히 권장합니다.

`src/`의 이미지

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

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

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

다음 예시는 이미지 자체의 height 및 width 속성을 사용하여 누적 레이아웃 이동 (CLS)을 방지하고 핵심 웹 바이탈을 개선합니다.

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

`public/`의 이미지

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

<img src="/images/public-cat.jpg" alt="자고있는 고양이" >

원격 이미지

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

<img src="https://example.com/remote-cat.jpg" alt="자고있는 고양이" >

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

<Image /> 컴포넌트는 CLS를 방지하기 위해 이미지를 최적화하고 원본 가로 및 세로 비율을 기반으로 (처리할 수 있는 이미지의 경우) 너비와 높이를 추론합니다. 가능하면 .astro 파일에서 이미지를 사용하는 것이 좋습니다.

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

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

CMS 또는 CDN의 이미지 사용

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

또는 CDN이 자체 SDK를 제공하여 Astro 프로젝트에 더 쉽게 통합할 수도 있습니다. 예를 들어, Cloudinary는 이미지를 CldImage 컴포넌트에 쉽게 넣을 수 있는 Astro SDK 또는 Node.js 환경에서 <img> 태그와 함께 사용할 URL을 생성할 수 있는 Node.js SDK를 지원합니다.

<Image /> 및 <Picture /> 컴포넌트의 전체 API 참조를 확인하세요.

원격 이미지 승인

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

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

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

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

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

export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});

콘텐츠 컬렉션의 이미지

콘텐츠 컬렉션의 이미지는 사용 중인 파일 형식에 따라 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 도우미를 사용하면 이미지를 검증하고 가져올 수 있습니다.

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

const blogCollection = defineCollection({
  schema: ({ image }) => z.object({
    title: z.string(),
    cover: image(),
    coverAlt: z.string(),
  }),
});

export const collections = {
  blog: blogCollection,
};

이미지를 가져와서 메타데이터로 변환하므로 이를 Astro 컴포넌트에 있는 <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>
  ))
}

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

getImage() 함수는 HTML이 아닌 다른 곳 (예: API 경로)에서 사용할 이미지를 생성하기 위한 것입니다. 현재 <Picture> 및 <Image> 컴포넌트가 지원하지 않는 옵션이 필요한 경우, getImage() 함수를 사용하여 사용자 정의 <Image /> 컴포넌트를 생성할 수 있습니다.

getImage() 참조에서 자세히 알아보세요.

관련 레시피: 사용자 정의 이미지 컴포넌트 빌드

대체 텍스트

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

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

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

기본 이미지 서비스

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

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

pnpm add sharp

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

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

Sharp의 이미지 처리를 방지하려면 passthroughImageService()를 구성하세요.

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

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

자산 캐싱

Astro는 사이트 빌드 중에 로컬 이미지와 승인된 소스의 원격 이미지에 대해 처리된 이미지 자산을 캐시 디렉터리에 저장합니다. 빌드 간에 캐시 디렉터리를 보존하면 처리된 자산이 재사용되어 빌드 시간과 대역폭 사용량이 개선됩니다.

기본 캐시 디렉터리는 ./node_modules/.astro이지만, cacheDir 구성 설정을 사용하여 변경할 수 있습니다.

원격 이미지

자산 캐시의 원격 이미지는 HTTP 캐싱을 기반으로 관리되며, 원격 서버가 반환하는 Cache-Control 헤더를 준수합니다. 이미지는 Cache-Control 헤더가 허용하는 경우 캐시되며, fresh가 유지되는 동안 사용됩니다.

재검증

추가된 버전: astro@5.1.0

재검증은 만료된 캐시 이미지가 여전히 최신 상태인지 원격 서버에 확인하여 대역폭 사용량과 빌드 시간을 줄입니다. 서버가 이미지를 여전히 신선하다고 표시하면 캐시된 버전이 재사용되고, 그렇지 않으면 이미지가 다시 다운로드됩니다.

재검증을 위해서는 원격 서버가 응답과 함께 Last-Modified 및/또는 Etag (엔티티 태그) 헤더를 전송해야 합니다. 이 기능은 If-Modified-Since와 If-None-Match 헤더를 지원하는 원격 서버에서 사용할 수 있습니다.

커뮤니티 통합

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

기여하기 커뮤니티 후원하기

이미지

이미지 저장 위치

src/ vs public/

원격 이미지

.astro 파일의 이미지

Markdown 파일의 이미지

MDX 파일의 이미지

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

Astro 컴포넌트의 이미지

<Image />

<Picture />

반응형 이미지 동작

생성된 반응형 이미지 HTML 출력

반응형 이미지 스타일

Tailwind 4와 반응형 이미지

SVG 컴포넌트

SVG 컴포넌트 속성

사용자 정의 이미지 컴포넌트 만들기

HTML의 <img> 태그를 사용하여 처리되지 않은 이미지 표시

src/의 이미지

public/의 이미지

원격 이미지

<Image /> vs <img> 선택

CMS 또는 CDN의 이미지 사용

원격 이미지 승인

콘텐츠 컬렉션의 이미지

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

대체 텍스트

기본 이미지 서비스

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

자산 캐싱

원격 이미지

재검증

커뮤니티 통합

`src/` vs `public/`

`.astro` 파일의 이미지

`<Image />`

`<Picture />`

HTML의 `<img>` 태그를 사용하여 처리되지 않은 이미지 표시

`src/`의 이미지

`public/`의 이미지

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

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