🚀
Astro 치트시트

Astro 5.x/4.x 최신 완전 가이드: 아일랜드 아키텍처(Islands), 제로 JS(Zero-JS) 기본 렌더링, 클라이언트 디렉티브(client:load/visible), 컴포넌트 프론트매터 문법, 파일 기반 동적 라우팅(getStaticPaths), Content Collections(타입 안전 스키마), ViewTransitions(ClientRouter) 애니메이션 및 SSR 하이브리드 어댑터 배포
#astro#islands-architecture#ssg#ssr#zero-js#frontend#web-framework#typescript#content-collections#view-transitions최종 업데이트: 2026-10-10
Astro 치트시트 핵심 명령어 및 실전 가이드

## 1. 필수 사전 요건 & 시스템 요구사양 (Prerequisites & Setup)

### 💻 시스템 설치 및 실행 요구사양 (System Requirements)

| 항목 | 최소 사양 (Minimum) | 권장 사양 (Recommended) | 참고 및 비고 |
| :--- | :--- | :--- | :--- |
| **운영체제 (OS)** | Windows 10/11, macOS, Linux | macOS Sonoma, Ubuntu 22.04 LTS+, Windows 11 (WSL2) | Vite 기반 고성능 ES 모듈 빌드 환경 |
| **CPU** | 2 코어 이상 | 4 코어 ~ 8 코어 이상 | 대규모 마크다운/MDX 파싱 및 이미지 최적화 파이프라인 |
| **메모리 (RAM)** | 2 GB 이상 | 4 GB ~ 8 GB 이상 | Node.js 런타임 및 샤프(Sharp) 이미지 리사이징 캐시 |
| **디스크 (Storage)** | 500 MB 이상의 여유 공간 | 5 GB ~ 20 GB 이상의 고속 NVMe SSD | `node_modules` 및 `.astro` 빌드 캐시 보관 |
| **런타임 / 패키지 매니저** | Node.js 18.17.1+ 또는 20+ (LTS) | Node.js 22 LTS / pnpm 9+ / Bun 1.1+ | `pnpm` 또는 `bun` 사용 시 패키지 설치 속도 3~5배 향상 |

---

### 🚀 프로젝트 생성 & 디렉토리 구조

```bash
# [1] 공식 대화형 CLI로 최신 Astro 프로젝트 생성
npm create astro@latest my-astro-site
# 또는 pnpm / bun 사용
pnpm create astro@latest my-astro-site

# [2] 프로젝트 디렉토리 이동 및 개발 서버 실행
cd my-astro-site
npm install
npm run dev

# [3] 공식 통합 플러그인 1초 자동 추가 (React, Tailwind, Sitemap 등)
npx astro add react
npx astro add tailwind
npx astro add sitemap
```

#### 📁 표준 프로젝트 구조 (Standard Architecture)
```text
my-astro-site/
├── public/                 # 빌드 시 그대로 복사되는 정적 에셋 (favicon, robots.txt)
├── src/
│   ├── components/         # 재사용 가능한 UI 컴포넌트 (.astro, .jsx, .vue)
│   ├── layouts/            # 공통 페이지 뼈대 레이아웃 (BaseLayout.astro)
│   ├── pages/              # 파일 기반 라우팅 디렉토리 (HTML 및 API 엔드포인트)
│   │   ├── index.astro     # 루트 페이지 (/)
│   │   ├── about.astro     # /about 페이지
│   │   └── posts/
│   │       └── [id].astro  # 동적 라우트 (/posts/1, /posts/2)
│   ├── content/            # 타입 안전 마크다운/MDX 콘텐츠 컬렉션
│   │   └── blog/
│   └── content.config.ts   # Astro 5+ 콘텐츠 스키마 정의 파일
├── astro.config.mjs        # Astro 전역 환경 설정 파일 (Vite, 어댑터, 플러그인)
├── package.json
└── tsconfig.json           # strict 모드가 기본 활성화된 타입스크립트 설정
```

---

## 2. Astro 핵심 멘탈 모델: 아일랜드 아키텍처 (Islands Architecture)

Astro는 **콘텐츠 중심(Content-Driven)** 웹사이트를 위해 태어났으며, 기본적으로 클라이언트로 자바스크립트를 단 1바이트도 전송하지 않는 **제로 JS(Zero JavaScript by Default)** 철학을 가집니다.

### 📐 SPA vs 아일랜드 아키텍처 비교 다이어그램 (ASCII Diagram)

```text
[ 전통적인 React / Vue SPA ]
┌──────────────────────────────────────────────────────────┐
│  거대한 단일 자바스크립트 번들 (Heavy JS Bundle: 500KB+)  │
│  전체 페이지가 수화(Hydration)되기 전까지 사용자 인터랙션 차단 │
└──────────────────────────────────────────────────────────┘

[ Astro Islands (아일랜드 아키텍처) ]
┌──────────────────────────────────────────────────────────┐
│ Pure HTML / Scoped CSS (정적 마크업 - Zero JS, 초고속 로딩)│
│                                                          │
│  ┌───────────────────────┐      ┌─────────────────────┐  │
│  │ Interactive Header    │      │ Image Carousel      │  │
│  │ [client:load]         │      │ [client:visible]    │  │
│  │ (React 섬: 즉시 수화)  │      │ (Vue 섬: 스크롤 도달 시│  │
│  └───────────────────────┘      └─────────────────────┘  │
│                                                          │
│  순수 정적 본문 글 / 텍스트 / 푸터 (HTML만 렌더링, JS 없음)│
└──────────────────────────────────────────────────────────┘
```

### ⚡ 5대 클라이언트 디렉티브 (Client Directives) 수화 전략

Astro 컴포넌트 내부에서 React/Vue/Svelte 컴포넌트를 호출할 때, 언제 브라우저에서 JS를 로드할지 결정합니다:

| 디렉티브 | 동작 시점 및 수화 타이밍 | 권장 실무 시나리오 |
| :--- | :--- | :--- |
| **`client:load`** | 페이지 로드 즉시 우선순위로 JS 다운로드 및 수화 | 상단 글로벌 네비게이션(GNB), 검색창, 다크모드 토글 |
| **`client:idle`** | 페이지 초기 로딩 완료 후 브라우저가 유휴(Idle) 상태일 때 로드 | 챗봇 위젯, 댓글 입력창, 알림 배지 |
| **`client:visible`** | 사용자가 스크롤하여 해당 컴포넌트가 화면(Viewport)에 나타날 때 | 하단 추천 상품 캐러셀, 복잡한 데이터 차트, 무한 스크롤 |
| **`client:media="(query)"`** | 지정한 CSS 미디어 쿼리가 일치할 때만 로드 | 모바일 햄버거 슬라이드 메뉴 (`client:media="(max-width: 768px)"`) |
| **`client:only="react"`** | 서버 렌더링(SSR)을 완전히 건너뛰고 클라이언트에서만 렌더링 | 브라우저 전용 API(`window`, `localStorage`, `Canvas`) 의존 UI |

---

## 3. [초보자 1단계] 3분 헬로월드: 컴포넌트 & 레이아웃 실습 (Hello World)

Astro 컴포넌트는 크게 상단 코드 펜스(`---`) 사이의 **서버 컴포넌트 스크립트(Frontmatter)**와 하단의 **HTML 템플릿 마크업**으로 구성됩니다.

### ① 공통 베이스 레이아웃 (`src/layouts/BaseLayout.astro`)

```astro
---
// src/layouts/BaseLayout.astro
interface Props {
  title: string;
  description?: string;
}

const { title, description = 'Astro로 제작된 초고속 모던 웹사이트' } = Astro.props;
---

<!doctype html>
<html lang="ko">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{title}</title>
    <meta name="description" content={description} />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
  </head>
  <body>
    <header class="site-header">
      <nav class="nav-container">
        <a href="/" class="brand-logo">🚀 Lucky Astro</a>
        <div class="nav-links">
          <a href="/">홈</a>
          <a href="/about">소개</a>
        </div>
      </nav>
    </header>

    <main class="site-main">
      <!-- 페이지별 본문 콘텐츠가 주입되는 슬롯 -->
      <slot />
    </main>

    <footer class="site-footer">
      <p>© 2026 LuckyTechWorld. All rights reserved.</p>
    </footer>
  </body>
</html>

<style>
  /* 컴포넌트 내부에 자동 스코프(Scoped)되는 CSS */
  body {
    margin: 0;
    font-family: system-ui, -apple-system, sans-serif;
    background: #0f172a;
    color: #f8fafc;
  }
  .nav-container {
    max-width: 960px;
    margin: 0 auto;
    padding: 1rem 1.5rem;
    display: flex;
    justify-content: space-between;
    align-items: center;
  }
  .brand-logo {
    color: #38bdf8;
    font-weight: 700;
    text-decoration: none;
    font-size: 1.25rem;
  }
  .nav-links a {
    color: #94a3b8;
    text-decoration: none;
    margin-left: 1rem;
  }
  .nav-links a:hover {
    color: #ffffff;
  }
  .site-main {
    max-width: 960px;
    margin: 2rem auto;
    padding: 0 1.5rem;
  }
  .site-footer {
    text-align: center;
    padding: 2rem 0;
    color: #64748b;
    border-top: 1px solid #1e293b;
  }
</style>
```

---

### ② 재사용 카드 컴포넌트 (`src/components/TechCard.astro`)

```astro
---
// src/components/TechCard.astro
interface Props {
  name: string;
  category: string;
  stars: number;
}

const { name, category, stars } = Astro.props;
---

<div class="tech-card">
  <span class="category-badge">{category}</span>
  <h3 class="tech-name">{name}</h3>
  <div class="card-footer">
    <span class="stars">⭐ {stars.toLocaleString()}</span>
    <!-- 추가 커스텀 슬롯 지원 -->
    <slot />
  </div>
</div>

<style>
  .tech-card {
    background: #1e293b;
    border: 1px solid #334155;
    border-radius: 10px;
    padding: 1.25rem;
    transition: transform 0.2s, border-color 0.2s;
  }
  .tech-card:hover {
    transform: translateY(-4px);
    border-color: #38bdf8;
  }
  .category-badge {
    font-size: 0.75rem;
    color: #38bdf8;
    background: rgba(56, 189, 248, 0.1);
    padding: 0.25rem 0.5rem;
    border-radius: 4px;
    font-weight: 600;
  }
  .tech-name {
    margin: 0.75rem 0;
    font-size: 1.25rem;
  }
  .card-footer {
    display: flex;
    justify-content: space-between;
    align-items: center;
    font-size: 0.875rem;
    color: #94a3b8;
  }
</style>
```

---

### ③ 메인 홈 페이지 (`src/pages/index.astro`)

```astro
---
// src/pages/index.astro
import BaseLayout from '../layouts/BaseLayout.astro';
import TechCard from '../components/TechCard.astro';

// 프론트매터: 서버 빌드 시점에 실행되는 순수 자바스크립트/타입스크립트
const pageTitle = "Astro 기술 스택 대시보드";
const techList = [
  { name: "Astro 5", category: "Web Framework", stars: 46000 },
  { name: "React 19", category: "UI Library", stars: 220000 },
  { name: "Tailwind CSS", category: "Styling", stars: 81000 },
];
---

<BaseLayout title={pageTitle}>
  <section class="hero-section">
    <h1>환영합니다! <span class="highlight">Astro 세상에 오신 것을</span></h1>
    <p>서버 빌드 시점에 렌더링되어 자바스크립트 부담 없이 번개처럼 빠릅니다.</p>
  </section>

  <section class="card-grid">
    {techList.map((tech) => (
      <TechCard name={tech.name} category={tech.category} stars={tech.stars}>
        <span class="status-dot">정상 작동</span>
      </TechCard>
    ))}
  </section>
</BaseLayout>

<style>
  .hero-section {
    text-align: center;
    margin-bottom: 3rem;
  }
  .highlight {
    background: linear-gradient(135deg, #38bdf8, #818cf8);
    -webkit-background-clip: text;
    -webkit-text-fill-color: transparent;
  }
  .card-grid {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
    gap: 1.5rem;
  }
  .status-dot {
    color: #10b981;
    font-weight: 600;
    font-size: 0.8rem;
  }
</style>
```

---

## 4. [2단계] 핵심 기능: 파일 기반 라우팅 & 동적 라우트 (Routing)

Astro는 `src/pages/` 디렉토리 하위의 파일 경로를 바탕으로 웹 URL을 자동 생성합니다.

### 🌐 라우팅 규칙 매핑

| 파일 경로 | 브라우저 요청 URL | 유형 |
| :--- | :--- | :--- |
| `src/pages/index.astro` | `/` | 루트 홈 페이지 |
| `src/pages/about.astro` | `/about` | 단일 정적 페이지 |
| `src/pages/blog/index.astro` | `/blog` | 블로그 목록 페이지 |
| `src/pages/blog/[slug].astro` | `/blog/hello-world` | 정적/동적 파라미터 라우트 |
| `src/pages/docs/[...slug].astro` | `/docs/guide/install` | 전역 일치(Catch-all) 라우트 |
| `src/pages/404.astro` | (일치하지 않는 모든 URL) | 커스텀 404 에러 페이지 |

---

### 📄 정적 사이트 동적 라우트 (`src/pages/posts/[id].astro`)

기본 정적 모드(SSG)에서는 `getStaticPaths()` 함수를 반드시 export하여 빌드할 페이지 목록(params 및 props)을 사전에 정의해야 합니다.

```astro
---
// src/pages/posts/[id].astro
import BaseLayout from '../../layouts/BaseLayout.astro';

// [1] 빌드 시점에 생성할 모든 경로(Paths) 반환
export async function getStaticPaths() {
  // 실제 환경에서는 외부 CMS나 DB, Markdown 컬렉션에서 조회
  const posts = [
    { id: '1', title: 'Astro 아일랜드의 비밀', content: '아일랜드는 필요한 부분만 수화합니다.' },
    { id: '2', title: 'Content Collections 완벽 가이드', content: 'Zod 스키마로 타입을 엄격히 검증합니다.' },
    { id: '3', title: 'Astro 5 신기능 총정리', content: '새로운 Content Layer API가 도입되었습니다.' },
  ];

  return posts.map((post) => ({
    params: { id: post.id },
    props: { post },
  }));
}

// [2] 현재 요청된 파라미터 및 props 수신
const { id } = Astro.params;
const { post } = Astro.props;
---

<BaseLayout title={`${post.title} - 게시글 #${id}`}>
  <article class="post-detail">
    <a href="/" class="back-link">← 목록으로 돌아가기</a>
    <h1 class="post-title">{post.title}</h1>
    <div class="post-meta">게시글 ID: <code>{id}</code></div>
    <div class="post-body">
      <p>{post.content}</p>
    </div>
  </article>
</BaseLayout>

<style>
  .post-detail {
    background: #1e293b;
    padding: 2rem;
    border-radius: 12px;
  }
  .back-link {
    color: #38bdf8;
    text-decoration: none;
    font-size: 0.9rem;
  }
  .post-title {
    margin: 1rem 0;
  }
  .post-meta {
    color: #64748b;
    font-size: 0.85rem;
    margin-bottom: 1.5rem;
  }
</style>
```

---

## 5. [2단계] Content Collections: 타입 안전 콘텐츠 관리 (Content Collections)

Astro 5+에서는 더욱 강력해진 **Content Layer API**를 통해 로컬 마크다운뿐 아니라 원격 API, DB 데이터까지 Zod 스키마로 완벽하게 타입 검증합니다.

### ① 스키마 정의 (`src/content.config.ts`)

```typescript
// src/content.config.ts
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

// 블로그 컬렉션 정의
const blog = defineCollection({
  // src/content/blog 디렉토리의 모든 md, mdx 파일 탐색
  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };
```

---

### ② 마크다운 본문 파싱 및 렌더링 (`src/pages/blog/[...slug].astro`)

```astro
---
// src/pages/blog/[...slug].astro
import { getCollection, render } from 'astro:content';
import BaseLayout from '../../layouts/BaseLayout.astro';

export async function getStaticPaths() {
  // 초안(draft)이 아닌 글만 필터링
  const posts = await getCollection('blog', ({ data }) => !data.draft);
  return posts.map((post) => ({
    params: { slug: post.id },
    props: { post },
  }));
}

const { post } = Astro.props;
// Astro 5의 render() 함수를 통해 마크다운 파싱 컴포넌트 획득
const { Content, headings } = await render(post);
---

<BaseLayout title={post.data.title} description={post.data.description}>
  <article class="blog-article">
    <h1>{post.data.title}</h1>
    <p class="date">발행일: {post.data.pubDate.toLocaleDateString('ko-KR')}</p>
    <div class="tags">
      {post.data.tags.map((tag) => <span class="tag">#{tag}</span>)}
    </div>
    <hr />

    <!-- 변환된 마크다운 본문 자동 출력 -->
    <div class="markdown-content">
      <Content />
    </div>
  </article>
</BaseLayout>

<style>
  .date { color: #94a3b8; font-size: 0.9rem; }
  .tag { background: #334155; padding: 2px 6px; border-radius: 4px; margin-right: 6px; font-size: 0.8rem; }
  .markdown-content { line-height: 1.8; color: #e2e8f0; }
</style>
```

---

## 6. [3단계] 실무 응용: UI 프레임워크 아일랜드 & 전역 상태 공유 (Frameworks & Nano Stores)

하나의 Astro 페이지 안에서 **React 컴포넌트**와 **Vue 컴포넌트**를 동시에 구동하고, 초경량 상태 관리 라이브러리인 **Nano Stores**를 통해 프레임워크 간 양방향 상태를 공유합니다.

### ① 공통 전역 스토어 정의 (`src/stores/cart.ts`)

```typescript
// src/stores/cart.ts
import { atom } from 'nanostores';

export interface CartItem {
  id: string;
  name: string;
  price: number;
}

// 장바구니 아이템 배열 스토어
export const $cart = atom<CartItem[]>([]);

// 아이템 추가 액션
export function addToCart(item: CartItem) {
  $cart.set([...$cart.get(), item]);
}
```

---

### ② React 컴포넌트: 상품 추가 버튼 (`src/components/AddToCartButton.tsx`)

```tsx
// src/components/AddToCartButton.tsx
import React from 'react';
import { addToCart, type CartItem } from '../stores/cart';

export default function AddToCartButton({ item }: { item: CartItem }) {
  return (
    <button
      onClick={() => addToCart(item)}
      className="px-4 py-2 bg-blue-600 hover:bg-blue-500 text-white rounded font-medium"
    >
      React 섬: 장바구니 담기 ({item.price.toLocaleString()}원)
    </button>
  );
}
```

---

### ③ Vue 컴포넌트: 실시간 장바구니 카운터 (`src/components/CartCounter.vue`)

```vue
<!-- src/components/CartCounter.vue -->
<template>
  <div class="vue-counter">
    <span>Vue 섬 장바구니: <strong>{{ cartItems.length }}</strong> 개</span>
  </div>
</template>

<script setup lang="ts">
import { useStore } from '@nanostores/vue';
import { $cart } from '../stores/cart';

// Nano Stores 반응형 바인딩
const cartItems = useStore($cart);
</script>

<style scoped>
.vue-counter {
  background: #064e3b;
  color: #34d399;
  padding: 0.5rem 1rem;
  border-radius: 6px;
  font-weight: 600;
}
</style>
```

---

### ④ Astro 페이지에서 두 프레임워크 결합 (`src/pages/shop.astro`)

```astro
---
// src/pages/shop.astro
import BaseLayout from '../layouts/BaseLayout.astro';
import AddToCartButton from '../components/AddToCartButton.tsx';
import CartCounter from '../components/CartCounter.vue';

const sampleItem = { id: 'p1', name: 'Astro 후드티', price: 49000 };
---

<BaseLayout title="멀티 프레임워크 쇼핑몰">
  <div class="shop-header">
    <h1>프레임워크 아일랜드 연동</h1>
    <!-- Vue 섬: 상시 로드 -->
    <CartCounter client:load />
  </div>

  <div class="product-box">
    <h2>{sampleItem.name}</h2>
    <!-- React 섬: 즉시 로드 및 클릭 이벤트 수신 -->
    <AddToCartButton client:load item={sampleItem} />
  </div>
</BaseLayout>
```

---

## 7. [3단계] 실무 응용: ViewTransitions & API 엔드포인트 & SSR (Transitions & SSR)

### 🎬 SPA 부드러운 화면 전환: ClientRouter (View Transitions)

페이지 전체 새로고침 없이 모바일 앱처럼 매끄럽게 화면이 전환되도록 `<ClientRouter />`를 헤더에 추가합니다.

```astro
---
// src/layouts/BaseLayout.astro (상단 추가)
import { ClientRouter } from 'astro:transitions';
---
<head>
  <!-- Astro 5 표준 (Astro 4에서는 ViewTransitions) -->
  <ClientRouter />
</head>
```

---

### 🔌 백엔드 REST API 엔드포인트 (`src/pages/api/posts.json.ts`)

서버리스 함수나 Node.js 백엔드로 동작하는 API 라우트입니다.

```typescript
// src/pages/api/posts.json.ts
import type { APIRoute } from 'astro';

export const GET: APIRoute = async ({ request, url }) => {
  const data = [
    { id: 1, title: 'Astro 5 Release', views: 1250 },
    { id: 2, title: 'Islands Deep Dive', views: 3400 },
  ];

  return new Response(JSON.stringify(data), {
    status: 200,
    headers: {
      'Content-Type': 'application/json; charset=utf-8',
      'Cache-Control': 'public, max-age=60',
    },
  });
};

export const POST: APIRoute = async ({ request }) => {
  const body = await request.json();

  return new Response(JSON.stringify({ success: true, received: body }), {
    status: 201,
    headers: { 'Content-Type': 'application/json' },
  });
};
```

---

### 🌐 SSR 하이브리드(Hybrid) 렌더링 어댑터 설정

일부 동적 로그인 세션 페이지나 실시간 API만 서버에서 계산하고, 기본 페이지는 정적 HTML(SSG)로 생성합니다.

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node'; // 또는 @astrojs/cloudflare, @astrojs/vercel

export default defineConfig({
  // Astro 5에서는 output: 'static'이 기본이며, 페이지별 export const prerender = false 선언
  adapter: node({
    mode: 'standalone', // 독립형 Node.js 웹서버 실행
  }),
});
```

```astro
---
// src/pages/dashboard.astro (동적 SSR 페이지 선언)
export const prerender = false;

// 매 요청마다 쿠키 확인 및 실시간 사용자 인증
const sessionCookie = Astro.cookies.get('user_session');
if (!sessionCookie) {
  return Astro.redirect('/login');
}
---
<h1>실시간 SSR 대시보드 (사용자: {sessionCookie.value})</h1>
```

---

## 8. CLI 필수 명령어 & 빌드 환경 (CLI Commands & Config)

### 💻 필수 터미널 명령어

```bash
# [1] 로컬 개발 서버 시작 (기본 포트: 4321)
npx astro dev
# 특정 포트 지정 실행
npx astro dev --port 3000 --host

# [2] 프로덕션 정적 HTML 빌드 실행 (dist/ 폴더 생성)
npx astro build

# [3] 빌드된 프로덕션 아티팩트 로컬 미리보기 (Preview)
npx astro preview

# [4] 프로젝트 전체 타입스크립트 및 Astro 컴포넌트 검사
npx astro check

# [5] Astro 환경 및 설치된 의존성 상세 진단 보고서 출력
npx astro info
```

---

## 9. 실무 트러블슈팅 & 프로덕션 운영 체크리스트 (Troubleshooting & Best Practices)

### ⚠️ 초보자가 가장 흔히 겪는 5대 실수 및 해결책

| 증상 및 문제점 | 원인 분석 | 확실한 해결 가이드 |
| :--- | :--- | :--- |
| **프론트매터의 `console.log()`가 브라우저에 안 찍힘** | 프론트매터(`---`) 코드는 서버/빌드 시점에 실행됨 | 브라우저 콘솔에서 보려면 하단에 `<script>console.log(...)</script>` 태그를 사용 |
| **React 컴포넌트의 버튼 클릭(`onClick`)이 무반응** | 클라이언트 수화 디렉티브(`client:*`)를 지정하지 않음 | `<MyButton client:load />` 또는 `client:visible` 디렉티브 필수 명시 |
| **`document is not defined` / `window is not defined` 에러** | 서버 사이드 렌더링 시점에 브라우저 전용 객체에 접근함 | React는 `useEffect()`, Astro는 `<script>` 태그 안에서 브라우저 객체 접근 |
| **`getStaticPaths() returned undefined` 빌드 에러** | SSG 동적 라우트(`[slug].astro`)에서 배열을 반환하지 않음 | `return [{ params: { slug: 'a' } }]` 형식의 배열을 반드시 명시적으로 반환 |
| **외부 이미지 로딩 시 빌드 지연 및 대역폭 낭비** | 일반 `<img>` 태그를 사용해 원본 크기 그대로 전송됨 | Astro 내장 `<Image src={myImage} alt="설명" width={600} />` 최적화 컴포넌트 사용 |

---

### 🚀 프로덕션 배포 체크리스트 (Production Checklist)

1. **정적 사이트 주소(`site`) 명시**:
   `astro.config.mjs`에 `site: 'https://techworld.sulucky5.pe.kr'`를 반드시 설정하여 sitemap.xml 및 Canonical URL이 올바른 도메인으로 생성되도록 보장합니다.
2. **소셜 메타 태그 (OpenGraph)**:
   `<meta property="og:title" content={title} />`, `<meta property="og:image" content={new URL(image, Astro.site)} />` 등 절대 URL로 공유 이미지를 구성합니다.
3. **빌드 캐싱 최적화**:
   CI/CD 파이프라인(GitHub Actions)에서 `node_modules`와 `.astro` 디렉토리를 캐시하여 빌드 시간을 70% 이상 단축합니다.
💬
Astro 치트시트

의견 및 질문

댓글 수정

댓글 삭제
