컨텐츠로 건너뛰기

이미지

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

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

이미지 저장 위치

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

src/ vs public/

섹션 제목: src/ vs public/

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

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

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

원격 이미지

섹션 제목: 원격 이미지

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

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

.astro 파일의 이미지

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

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

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

최적화된 이미지를 위해 Astro의 기본 <Image /> 및 <Picture /> 컴포넌트를 가져와 사용합니다. 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.">
<Image /> 및 <Picture /> 컴포넌트의 전체 API 참조를 확인하세요.
관련 레시피: 동적으로 이미지 가져오기

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

섹션 제목: &lt;Image /&gt; 컴포넌트를 사용하여 최적화된 이미지 표시

기본으로 제공되는 <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."
/>

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

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

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

섹션 제목: HTML &lt;img&gt; 태그를 사용하여 처리되지 않은 이미지 표시

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

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

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

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

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

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

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

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

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

기본값 설정

섹션 제목: 기본값 설정

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

대안으로 재사용을 위해 이러한 컴포넌트를 다른 Astro 컴포넌트로 래핑할 수 있습니다. 예를 들어 속성을 props로 전달받고 각 이미지에 일관된 스타일을 적용하는 블로그 게시물 이미지 컴포넌트를 만들 수 있습니다.

src/components/BlogPostImage.astro
---
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의 원격 이미지만 최적화할 수 있습니다.

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

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

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

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

MDX 파일의 이미지

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

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

또한 가져오기가 필요 없는 표준 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)
<Image /> 및 <Picture /> 컴포넌트의 전체 API 참조를 확인하세요.

콘텐츠 컬렉션의 이미지

섹션 제목: 콘텐츠 컬렉션의 이미지

콘텐츠 컬렉션의 이미지는 사용 중인 파일 형식에 따라 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 프레임워크 컴포넌트의 이미지

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

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

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

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

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

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

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

getImage() 참조에서 자세히 알아보세요.
관련 레시피: 사용자 정의 이미지 컴포넌트 빌드

대체 텍스트

섹션 제목: 대체 텍스트

모든 사용자가 동일한 방식으로 이미지를 볼 수 있는 것은 아니므로 이미지를 사용할 때 접근성은 특히 중요한 고려사항입니다. 이미지에 대한 설명 대체 텍스트를 제공하려면 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 프로젝트의 이미지를 최적화하고 작업하기 위한 여러 타사 커뮤니티 이미지 통합이 있습니다.

기여하기

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

GitHub Issue 생성

우리에게 가장 빨리 문제를 알려줄 수 있어요.

커뮤니티
京ICP备15031610号-99