이미지(Images)

Astro는 내장 <Image />·<Picture /> 컴포넌트, Markdown 이미지 문법(!) 처리, SVG 컴포넌트, 그리고 이미지 생성 함수(getImage())를 제공해 이미지를 최적화·변환할 수 있어요. 이미지 저장 위치, .astro·Markdown·MDX 파일에서 쓰는 방법을 정리할게요.

출처: https://docs.astro.build/en/guides/images/

항상 Astro 컴포넌트를 쓸 필요는 없어요. .astro나 Markdown 파일에서 네이티브 HTML 요소로, 또는 MDX·JSX에서 <img />처럼 각 파일 타입의 표준 방식으로 이미지를 쓸 수도 있어요. 다만 이 경우 Astro가 이미지를 처리하거나 최적화하지 않아요.

이미지 저장 위치

`src/` vs `public/`

src/에 저장한 로컬 이미지는 .astro, .md, .mdx, .mdoc, 그리고 다른 UI 프레임워크 파일에서 파일 import로 모두 사용할 수 있어요. 이미지는 콘텐츠 옆을 포함해 어느 폴더에든 저장할 수 있어요.

원격 이미지는 콘텐츠 관리 시스템(CMS)이나 디지털 자산 관리(DAM) 플랫폼에 저장하고, API로 가져오거나 전체 URL 경로로 표시할 수도 있어요.

.astro 파일의 모든 이미지에 대해 src 속성의 값은 이미지 파일의 위치에 따라 결정돼요. 원격·public/ 이미지는 URL 경로를 쓰고, src/의 이미지는 import해서 참조해요.

`.astro` 파일에서의 이미지

Astro의 템플릿 언어는 <Image /> 컴포넌트로 최적화된 이미지를, <Picture /> 컴포넌트로 여러 크기·포맷을 생성해 렌더링할 수 있게 해줘요.

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

Astro 컴포넌트

`<Image />`

내장 <Image /> 컴포넌트는 src/ 폴더의 로컬 이미지와 승인된 원천의 원격 이미지의 최적화된 버전을 표시해요. 이미지의 크기·파일 타입·품질을 제어할 수 있고, 프리렌더링 페이지에서는 빌드 시점에, 온디맨드 렌더링 페이지에서는 보여질 때 변환이 일어나요.

<Image />는 이미지의 올바른 width와 height를 자동으로 설정해 Cumulative Layout Shift(CLS) 를 최적화해요. CLS는 로딩 중 콘텐츠가 얼마나 이동했는지 측정하는 Core Web Vital 지표예요.

`<Picture />`

내장 <Picture /> 컴포넌트는 이미지의 여러 포맷·크기로 <picture> 태그를 생성해요. 선호하는 파일 포맷을 지정하고 동시에 fallback 포맷도 제공할 수 있어요. 예를 들어 로컬 .png 파일을 avif와 webp 포맷으로 변환하고, 필요할 때 fallback으로 보여줄 .png의 <img>도 만들 수 있어요.

---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Picture src={myImage} formats={['avif', 'webp']} alt="A description of my image." />

반응형 이미지 동작

<Image /> 또는 <Picture />에 layout 속성을 적용하면 Astro가 필요한 srcset, sizes 값을 자동 생성하고 제대로 리사이즈되도록 스타일을 적용해요. constrained와 full-width 레이아웃의 이미지는 컨테이너에 맞게 리사이즈되는 스타일이 적용돼요.

SVG 컴포넌트

.astro 파일에서 SVG 파일을 import해서 Astro 컴포넌트로 사용할 수 있어요. width, height, fill 같은 속성을 넘겨서 렌더링할 수 있어요.

콘텐츠 컬렉션에서의 이미지

콘텐츠 컬렉션 항목에 연관 이미지를 선언할 수 있어요. 블로그 포스트의 커버 이미지처럼 cover 경로를 frontmatter에 상대 경로로 정의하면, image 헬퍼가 이미지를 검증·import하고 메타데이터로 변환해 <Image/>, <img>, getImage()의 src로 전달할 수 있어요.

`getImage()`로 이미지 생성

getImage()는 서버에서만 쓸 수 있어요. 결과 이미지 URL을 클라이언트에서 써야 한다면(클라이언트 스크립트나 프레임워크 컴포넌트에서), frontmatter 안에서 getImage()를 호출하고 그 src를 클라이언트에 전달하세요.

더 알아보기

<Image /> API 레퍼런스: https://docs.astro.build/en/reference/components-reference/
콘텐츠 컬렉션: https://docs.astro.build/en/guides/content-collections/
배포: https://docs.astro.build/en/guides/deploy/

이미지(Images)