이미지

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

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

이미지 저장 위치

`src/` vs `public/`

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

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

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

원격 이미지

또한 콘텐츠 관리 시스템 (CMS) 또는 디지털 자산 관리 (DAM) 플랫폼에 이미지를 원격으로 저장하도록 선택할 수도 있습니다. Astro는 API를 사용하여 원격으로 데이터를 가져오거나 전체 URL 경로를 이용하여 이미지를 표시할 수 있습니다.

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

`.astro` 파일의 이미지

.astro 파일에서 로컬 이미지는 상대 경로에서 가져와야 합니다. 이 가져오기는 이미지의 src 값을 제공합니다.

원격 및 public/ 이미지는 가져오기가 필요하지 않으며 대신 src에 대한 URL (사이트의 전체 또는 상대 경로)이 필요합니다.

최적화된 이미지를 위해 Astro의 기본 <Image /> 및 <Picture /> 컴포넌트를 가져와 사용합니다. 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.">

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

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

`<Image />` 컴포넌트를 사용하여 최적화된 이미지 표시

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

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

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

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

<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 />` 컴포넌트를 사용해 반응형 이미지 만들기

Added in: astro@3.3.0

다양한 형식 및 크기로 반응형 이미지를 표시하려면 내장된 <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 /> 컴포넌트의 속성에 대한 자세한 내용은 astro:assets 참조에서 알아보세요.

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

Astro 템플릿 구문은 최종 출력에 대한 완전한 제어를 위해 <img> 태그를 직접 작성하는 것도 지원합니다. 이러한 이미지는 처리 및 최적화되지 않습니다. 모든 HTML <img> 태그 속성을 허용하며, 필수 속성은 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="A barking dog." />

`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를 방지하기 위해 원본 가로 세로 비율을 기반으로 (처리할 수 있는 이미지의 경우) 너비와 높이를 추론합니다. 가능하면 .astro 파일로 이미지를 사용하는 것이 좋습니다.

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

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

기본값 설정

현재 모든 <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>

원격 이미지 승인

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" }],
  }
});

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 참조를 확인하세요.

Markdown 파일의 이미지

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

# 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 /> 및 <Picture /> 컴포넌트를 사용할 수 없습니다.

이미지 속성에 대한 더 많은 제어가 필요한 경우, Astro의 MDX 통합을 사용하여 .mdx 파일 형식에 대한 지원을 추가하는 것이 좋습니다. MDX를 사용하면 Markdown에 컴포넌트를 추가할 수 있으며, MDX에서 사용할 수 있는 추가 이미지 옵션도 제공됩니다.

MDX 파일의 이미지

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

또한 가져오기가 필요 없는 표준 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)

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

콘텐츠 컬렉션의 이미지

콘텐츠 컬렉션의 이미지는 사용 중인 파일 형식에 따라 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,
};

이미지를 가져와서 메타데이터로 변환하므로 이를 <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 프레임워크 컴포넌트의 이미지

다른 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>

또한 프레임워크의 자체 이미지 구문을 사용하여 이미지를 렌더링할 수 있습니다 (예: 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." />

`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가 유지되는 동안 사용됩니다.

재검증

Added in: astro@5.1.0 New

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

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

커뮤니티 통합

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

기여하기

커뮤니티

이미지

이미지 저장 위치

`src/` vs `public/`

원격 이미지

`.astro` 파일의 이미지

`<Image />` 컴포넌트를 사용하여 최적화된 이미지 표시

`<Picture />` 컴포넌트를 사용해 반응형 이미지 만들기

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

`public/`의 이미지

원격 이미지

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

기본값 설정

원격 이미지 승인

CMS 또는 CDN의 이미지 사용

Markdown 파일의 이미지

MDX 파일의 이미지

콘텐츠 컬렉션의 이미지

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

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

대체 텍스트

기본 이미지 서비스

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

자산 캐싱

원격 이미지

재검증

커뮤니티 통합

여러분의 생각을 들려주세요!

GitHub Issue 생성

의견 보내기

의견 보내기

이미지

이미지 저장 위치

src/ vs public/

원격 이미지

.astro 파일의 이미지

<Image /> 컴포넌트를 사용하여 최적화된 이미지 표시

<Picture /> 컴포넌트를 사용해 반응형 이미지 만들기

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

public/의 이미지

원격 이미지

<Image /> vs <img> 선택

기본값 설정

원격 이미지 승인

CMS 또는 CDN의 이미지 사용

Markdown 파일의 이미지

MDX 파일의 이미지

콘텐츠 컬렉션의 이미지

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

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

대체 텍스트

기본 이미지 서비스

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

자산 캐싱

원격 이미지

재검증

커뮤니티 통합

`src/` vs `public/`

`.astro` 파일의 이미지

`<Image />` 컴포넌트를 사용하여 최적화된 이미지 표시

`<Picture />` 컴포넌트를 사용해 반응형 이미지 만들기

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

`public/`의 이미지

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

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