Astro 4에서 Content Collections v2는 무엇이 달라졌나요?

루트의 content.config.ts와 로더(예: glob) 기반으로 컬렉션을 선언하고, 빌드 시점에 원격·로컬 소스를 통합해 타입 안전하게 검증할 수 있습니다. 기존 src/content/config.ts 단일 파일 패턴에서 벗어나 확장성이 좋아졌습니다.

View Transitions를 쓰면 SEO나 성능에 불리하지 않나요?

기본 HTML은 그대로 서빙되며 클라이언트에서 전환을 보강하는 패턴이라, 의미 있는 마크업·메타 태그·접근성만 지키면 SEO에 치명적이지 않습니다. 다만 불필요한 클라이언트 스크립트를 늘리지 않도록 전역 활성화 범위를 조절하는 것이 좋습니다.

Cloudflare Pages에서 Astro SSR을 쓰려면 어떤 어댑터를 써야 하나요?

@astrojs/cloudflare 어댑터를 설치하고 astro.config에서 출력 server로 지정합니다. 이 블로그(pkglog.com)도 Cloudflare Pages 배포를 전제로 한 설정 패턴을 참고할 수 있습니다.

Astro 4 완벽 가이드 — 빌드 성능, 콘텐츠 컬렉션 v2, 뷰 전환

2026년 4월 16일 · 40분 읽기 · 수정 2026년 4월 16일 중급 tutorial

이 글의 핵심

Astro 4는 정적 우선 아키텍처를 유지하면서 View Transitions, Content Layer(컬렉션 v2), 개발자 도구바 등으로 실무 생산성과 체감 성능을 강화했습니다. 이 글에서는 빌드 파이프라인 최적화, 타입 안전 콘텐츠, 페이지 전환 애니메이션, 다크모드, 주요 호스팅 플랫폼 배포 설정을 한 흐름으로 다룹니다.

이 글의 핵심

Astro 4는 콘텐츠 중심 웹사이트를 빠르게 만들기 위한 프레임워크로, 아일랜드 아키텍처(Island Architecture)로 기본적으로 JavaScript를 최소화합니다. 이 가이드는 빌드·개발 성능, Content Collections v2(콘텐츠 레이어), View Transitions(뷰 전환), 다크모드, Vercel·Netlify·Cloudflare Pages 배포를 실무 관점에서 연결해 설명합니다.

실무 관점: 마케팅·기술 블로그·문서 사이트에서는 “로딩 체감”과 “콘텐츠 수정 시 빌드 안정성”이 동시에 중요합니다. Astro 4는 타입 안전한 콘텐츠 파이프라인과 페이지 전환 UX를 함께 잡을 수 있어, 팀 단위 운영에 유리합니다.

Astro 4에서 달라진 점
프로젝트 생성과 기본 구조
Dev Toolbar로 아일랜드 점검
빌드·개발 성능 최적화
Content Collections v2와 content.config.ts
MDX와 인터랙티브 콘텐츠
View Transitions 실전 패턴
다크모드(클래스·전환 유지)
하이브리드·SSR 개요
배포: Vercel, Netlify, Cloudflare Pages
SEO와 구조화 데이터
체크리스트와 트러블슈팅

Astro 4 변경 요약 {#astro-4-변경-요약}

Astro 4.x 계열은 정적 사이트 생성(SSG) 을 기본값으로 유지하면서도, 다음과 같은 방향으로 생산성을 끌어올렸습니다.

영역	설명
개발 경험	Dev Toolbar로 컴포넌트·이벤트·아일랜드 의존성을 시각적으로 점검
콘텐츠	Content Layer — `content.config.ts`에서 로더(loader) 로 Markdown/MDX·원격 소스를 선언적으로 통합
UX	View Transitions — 브라우저 View Transitions API와 연동한 부드러운 페이지 전환
국제화	실험적 i18n 라우팅 등 라우팅 계층 개선(프로젝트 설정에 따라 활성화)

이후 Astro 5에서도 이 축(콘텐츠 레이어·View Transitions·어댑터)은 계승되므로, Astro 4에서 익힌 패턴은 상위 버전으로 자연스럽게 이어집니다.

프로젝트 생성 {#프로젝트-생성}

CLI로 생성

npm create astro@latest

Astro 4.x 대를 명시적으로 고정하려면 생성 후 package.json에서 "astro": "^4.16.0"처럼 메이저 4로 제한합니다. 팀 표준으로 문서화해 두면 재현 가능한 빌드가 유지됩니다.

대화형 프롬프트에서 템플릿(Blog, Docs 등) 과 TypeScript를 선택하면, 콘텐츠·페이지 스캐폴딩이 함께 생성됩니다.

`package.json` 스크립트

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}

astro build는 프로덕션 번들을 만들고, astro preview는 빌드 산출물을 로컬에서 검증할 때 사용합니다. 배포 플랫폼에서도 동일하게 npm run build 결과물을 게시하는 흐름이 일반적입니다.

Dev Toolbar는 개발 서버 실행 시 화면에 표시되는 오버레이로, 아일랜드 경계·클라이언트 지시어·성능 힌트를 빠르게 확인할 수 있습니다. 프로덕션 빌드에는 포함되지 않으므로, 번들 크기나 SEO에는 영향을 주지 않습니다.

실무에서는 다음 용도로 특히 유용합니다.

불필요한 client:load 탐지: 뷰포트 밖 컴포넌트가 과도하게 즉시 수화되는지 검토
레이아웃 시프트 원인 추적: 이미지·폰트 로딩과 연계된 CLS 이슈 조사
View Transitions 디버깅: 전환 중 유지되어야 할 DOM과 교체되는 영역 구분

팀 온보딩 문서에 “스테이징에서 Lighthouse, 로컬에서 Dev Toolbar” 를 한 줄로 적어 두면, 성능 회귀를 줄이는 데 도움이 됩니다.

빌드 성능 {#빌드-성능}

1) 출력 모드와 어댑터

정적(output: 'static'): 기본적으로 HTML·에셋을 빌드 시점에 생성. CDN 캐시에 매우 유리합니다.
서버(output: 'server') 또는 하이브리드: API·SSR이 필요할 때 어댑터(@astrojs/node, @astrojs/vercel, @astrojs/netlify, @astrojs/cloudflare 등)를 연결합니다.

// astro.config.mjs 예시 — 정적 사이트
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static',
  vite: {
    build: {
      cssMinify: true,
    },
  },
});

2) Vite 레벨 튜닝 포인트

Astro는 내부적으로 Vite를 사용하므로, vite.build, vite.ssr, vite.optimizeDeps 등으로 번들 분할·의존성 사전 번들을 조정할 수 있습니다. 다만 과도한 커스텀은 빌드 캐시를 깨기 쉬우므로, 측정 후 최소 변경을 권장합니다.

3) 이미지 최적화

astro:assets의 Image 컴포넌트로 로컬 이미지를 빌드 시 최적화합니다. CLS(누적 레이아웃 이동) 와 LCP(최대 콘텐츠 페인트) 개선에 직접적으로 기여합니다.

---
import { Image } from 'astro:assets';
import hero from '../assets/hero.jpg';
---
<Image src={hero} alt="히어로 이미지" width={1200} height={630} loading="eager" />

4) 클라이언트 JS 억제(아일랜드)

프레임워크 컴포넌트는 client:* 지시어로만 묶습니다. 불필요한 client:load 남발은 TTI(상호작용까지 시간) 를 악화시킵니다.

---
import Counter from '../components/Counter.tsx';
---
<!-- 뷰포트에 들어올 때만 수화 -->
<Counter client:visible />

콘텐츠 컬렉션 v2 {#콘텐츠-컬렉션-v2}

Astro 4 이후 권장 패턴은 프로젝트 루트의 content.config.ts 에서 컬렉션을 정의하고, glob 등 로더로 src/content 이하 파일을 수집하는 것입니다. Zod 스키마로 frontmatter를 검증하므로, 오타·누락을 빌드 시점에 걸러낼 수 있습니다.

`content.config.ts` 예시

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
    level: z.enum(['초급', '중급', '고급']).optional(),
  }),
});

export const collections = { blog };

페이지에서 조회

---
import { getCollection } from 'astro:content';

const posts = await getCollection('blog', ({ data }) => !data.draft);
const sorted = posts.sort(
  (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf()
);
---
<ul>
  {sorted.map((post) => (
    <li>
      <a href={`/blog/${post.id}`}>{post.data.title}</a>
    </li>
  ))}
</ul>

post.id는 glob 로더의 base·파일 경로에 따라 결정됩니다. 이 저장소(pkglog.com)의 한국어 블로그처럼 [...slug].astro에서 params.slug에 post.id를 넘기는 패턴이면, 목록의 href도 동일한 규칙을 써야 깨지지 않습니다.

동적 라우트에서는 render(post)로 MDX·Markdown 본문을 렌더링합니다. 엔트리 조회가 필요할 때는 getEntry('blog', slug)를 사용합니다.

콘텐츠 v2를 쓰는 이유

스키마 검증: 운영 중 잘못된 frontmatter로 빌드가 깨지는 문제를 조기에 차단
로더 확장: 동일한 파이프라인으로 로컬 MDX·원격 CMS 등을 통합할 여지
타입 생성: 에디터 자동완성과 data 필드 접근 안정성 향상

MDX 콘텐츠 {#mdx-콘텐츠}

컬렉션에서 **/*.{md,mdx} 패턴을 허용하면, 글 안에서 UI 컴포넌트를 직접 가져와 설명과 함께 배치할 수 있습니다. MDX는 아일랜드와 결합할 때 가장 빛을 발합니다. 인터랙션은 작은 단위로 나누고 client:visible 또는 client:idle로 지연 수화하는 편이 안전합니다.

---
title: '샘플 MDX'
description: 'MDX에서 컴포넌트 사용'
pubDate: 2026-04-16
---

import Chart from '../../components/Chart.tsx';

## 실시간 예제

아래 차트는 스크롤 후에만 수화됩니다.

<Chart client:visible />

MDX에서 과도한 클라이언트 번들이 들어오지 않도록, 공통 차트·코드 에디터 래퍼를 한두 개의 추상화로 묶고 나머지 글에서는 재사용하는 것이 유지보수에 유리합니다.

뷰 전환 {#뷰-전환}

View Transitions는 페이지 이동 시 전역 레이아웃 유지·부드러운 전환을 제공합니다. Astro는 astro:transitions를 통해 이를 래핑합니다.

레이아웃에 전역 활성화

---
import { ViewTransitions } from 'astro:transitions';
---
<html lang="ko">
  <head>
    <meta charset="utf-8" />
    <ViewTransitions />
  </head>
  <body>
    <slot />
  </body>
</html>

링크별 `transition` 힌트

<a href="/blog/hello" transition:animate="slide">글로 이동</a>

`transition:persist`로 사이드바·헤더 유지

동일 레이아웃의 헤더·사이드바·오디오 플레이어 등은 페이지 전환 후에도 유지하고 싶을 때가 많습니다. 해당 루트에 transition:persist 를 지정하면, DOM 스냅샷이 유지되어 깜빡임 없이 이어집니다.

<aside transition:persist="sidebar">
  <nav>...</nav>
</aside>

전환 이후 스크립트: `astro:page-load`

View Transitions는 HTML을 교체하는 방식이므로, 전역 DOMContentLoaded에만 의존한 스크립트는 재실행되지 않을 수 있습니다. Astro는 astro:page-load 커스텀 이벤트로 각 탐색 이후 훅을 제공합니다.

<script>
  document.addEventListener('astro:page-load', () => {
    // 페이지마다 초기화해야 하는 분석·짧은 UI 스크립트
  });
</script>

전환 시 스크롤·상태 이슈

긴 글에서 스크롤 위치 복원이 기대와 다를 수 있으므로, 필요 시 transition:persist 로 특정 DOM을 유지합니다.
이벤트 리스너가 중복 등록되지 않도록, 클라이언트 컴포넌트는 client:* 범위와 라이프사이클을 명확히 나눕니다.

다크모드 {#다크모드}

다크모드는 보통 class 전략(예: html.dark) 또는 prefers-color-scheme 를 조합합니다. View Transitions와 함께 쓸 때는 깜빡임(FOUC) 을 막기 위해 인라인 초기 스크립트로 선호를 먼저 적용하는 패턴이 흔합니다.

레이아웃 예시: `localStorage` + `class`

---
const title = 'Astro 4 가이드';
---
<!doctype html>
<html lang="ko" class="bg-white text-gray-900 dark:bg-gray-950 dark:text-gray-100">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>{title}</title>
    <script is:inline>
      (function () {
        const k = 'theme';
        const stored = localStorage.getItem(k);
        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
        if (stored === 'dark' || (!stored && prefersDark)) {
          document.documentElement.classList.add('dark');
        } else {
          document.documentElement.classList.remove('dark');
        }
      })();
    </script>
  </head>
  <body>
    <button
      type="button"
      id="theme-toggle"
      class="rounded border px-3 py-1 text-sm dark:border-gray-600"
    >
      테마 전환
    </button>
    <slot />
    <script>
      const btn = document.getElementById('theme-toggle');
      btn?.addEventListener('click', () => {
        const root = document.documentElement;
        const next = root.classList.toggle('dark') ? 'dark' : 'light';
        localStorage.setItem('theme', next === 'dark' ? 'dark' : 'light');
      });
    </script>
  </body>
</html>

Tailwind CSS를 쓰는 경우 darkMode: 'class' 설정과 위 패턴이 잘 맞습니다. CSS 변수로 색 토큰을 정의하면, 테마 전환 시 한 번의 class 토글로 전역이 일관되게 바뀝니다.

View Transitions를 켠 상태에서 테마가 한 프레임 잘못 적용되는 현상이 보이면, document.documentElement에 대한 class 적용을 astro:after-swap 훅에서 한 번 더 동기화하는 방법도 있습니다. 다만 복잡도가 올라가므로, 우선 인라인 초기화 스크립트로 FOUC를 막는 것이 1순위입니다.

하이브리드 {#하이브리드}

일부 경로만 서버에서 렌더하고 나머지는 정적으로 두고 싶다면 output: 'hybrid'(또는 이후 버전에서 권장되는 output: 'static' + 어댑터와의 조합 문서)를 검토합니다. Astro 4 시점에서는 인증이 필요한 페이지·요청 시점 데이터처럼 정적 생성이 부적절한 소수 경로에 선택적으로 SSR을 얹는 패턴이 일반적입니다.

하이브리드·SSR을 쓰면 캐시 전략(CDN·Cache-Control·에지 키)이 정적 사이트보다 복잡해집니다. 기본은 정적, 정말 필요한 라우트만 동적이라는 최소 범위 원칙을 추천합니다.

배포 {#배포}

공통: `astro build` 산출물

정적 모드에서는 dist/ 가 기본 출력입니다. 각 플랫폼은 이 디렉터리를 빌드 커맨드와 함께 지정합니다.

Vercel

프레임워크 프리셋: Astro
Build Command: npm run build
Output Directory: dist
SSR 시 @astrojs/vercel 어댑터와 output: 'server' 또는 hybrid 설정

// astro.config.mjs — SSR 예시 (필요 시)
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});

Netlify

Build command: npm run build
Publish directory: dist
SSR 시 @astrojs/netlify 어댑터 사용

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  output: 'server',
  adapter: netlify(),
});

Cloudflare Pages

정적 배포는 동일하게 dist 를 게시합니다. SSR·에지가 필요하면 @astrojs/cloudflare 를 사용합니다. 이 저장소(pkglog.com)도 Cloudflare Pages 배포를 전제로 두는 경우가 많아, 환경 변수·캐시 무효화·Node 호환성만 런타임 문서와 맞추면 됩니다.

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});

SEO 최적화 구조

메타·구조화 데이터

title / description: 검색 결과 스니펫의 핵심. 페이지별로 유일하게 작성합니다.
Open Graph / Twitter 카드: 소셜 공유 시 전환율에 영향.
시맨틱 HTML: article, h1 단일, header/nav/main 구획을 명확히.

Astro에서의 패턴

BaseHead.astro 같은 공통 컴포넌트에 canonical, OG 이미지, JSON-LD를 모아 두고, 블로그 글에서는 frontmatter의 요약·작성일을 주입합니다. 이 블로그의 스키마는 summaryTop, faq 등을 리치 결과에 맞게 확장할 수 있도록 설계하는 것이 좋습니다.

Article JSON-LD 예시

---
const { title, description, pubDate, canonicalURL } = Astro.props;
const jsonLd = {
  '@context': 'https://schema.org',
  '@type': 'Article',
  headline: title,
  description,
  datePublished: pubDate?.toISOString?.() ?? pubDate,
  mainEntityOfPage: canonicalURL,
};
---
<script type="application/ld+json" set:html={JSON.stringify(jsonLd)} />

검색엔진은 일관된 날짜 형식과 canonical을 통해 중복 URL을 통합합니다. 블로그 플랫폼을 옮길 때도 리디렉션·canonical을 함께 계획하는 것이 안전합니다.

트러블슈팅 {#트러블슈팅}

증상	점검
빌드 시 콘텐츠 스키마 오류	`content.config.ts`의 Zod 필드와 Markdown frontmatter 키가 일치하는지
View Transitions 후 스크립트 중복	`client:only`/`client:load` 범위와 `transition:persist` 사용 여부
이미지 경로 오류	`astro:assets`는 기본적으로 상대 import 경로를 요구하는 경우가 많음
Cloudflare SSR 빌드 실패	Node 전용 패키지가 에지 번들에 섞이지 않는지, 어댑터 문서의 호환성 확인

정리

Astro 4는 적은 JavaScript로 빠른 첫 로드를 유지하면서, Content Collections v2로 콘텐츠 품질을 빌드 타임에 보장하고, View Transitions로 체감 UX를 끌어올릴 수 있습니다. 여기에 다크모드·이미지·아일랜드 로딩까지 묶으면, 기술 블로그·문서·마케팅 사이트에서 성능·운영·검색 요구를 균형 있게 만족시킬 수 있습니다.

배포는 Vercel·Netlify·Cloudflare Pages 모두 astro build를 표준으로 삼되, SSR 필요 여부에 따라 어댑터만 선택하면 됩니다. 변경 후에는 반드시 git push 후 npm run deploy 순서를 지키고, 프로덕션에서 Lighthouse·실제 라우팅 전환을 한 번씩 검증하는 것을 권장합니다.

이 글의 핵심

이 글의 핵심

목차

Astro 4 변경 요약 {#astro-4-변경-요약}

프로젝트 생성 {#프로젝트-생성}

CLI로 생성

package.json 스크립트

Dev Toolbar

빌드 성능 {#빌드-성능}

1) 출력 모드와 어댑터

2) Vite 레벨 튜닝 포인트

3) 이미지 최적화

4) 클라이언트 JS 억제(아일랜드)

콘텐츠 컬렉션 v2 {#콘텐츠-컬렉션-v2}

content.config.ts 예시

페이지에서 조회

콘텐츠 v2를 쓰는 이유

MDX 콘텐츠 {#mdx-콘텐츠}

뷰 전환 {#뷰-전환}

레이아웃에 전역 활성화

링크별 transition 힌트

transition:persist로 사이드바·헤더 유지

전환 이후 스크립트: astro:page-load

전환 시 스크롤·상태 이슈

다크모드 {#다크모드}

레이아웃 예시: localStorage + class

하이브리드 {#하이브리드}

배포 {#배포}

공통: astro build 산출물

Vercel

Netlify

Cloudflare Pages

SEO 최적화 구조

메타·구조화 데이터

Astro에서의 패턴

Article JSON-LD 예시

트러블슈팅 {#트러블슈팅}

정리

`package.json` 스크립트

`content.config.ts` 예시

링크별 `transition` 힌트

`transition:persist`로 사이드바·헤더 유지

전환 이후 스크립트: `astro:page-load`

레이아웃 예시: `localStorage` + `class`

공통: `astro build` 산출물