Astro 블로그 설치부터 동작 확인까지 — 처음부터 끝까지 따라하는 완벽 가이드 (2026)

Astro로 블로그를 만들겠다고 결심했다면, 가장 먼저 부딪치는 벽은 “어디서부터 시작하지?” 입니다. Node 버전은 어떻게 맞추고, 어떤 명령어를 쳐야 하고, 잘 깔린 건지 어떻게 확인하나요?

이 글은 macOS / Windows / Linux 어디서든 Astro 블로그를 처음부터 끝까지 설치하고, 개발 서버가 잘 뜨는지·빌드가 잘 되는지·배포 직전 상태가 정상인지까지 한 번에 검증할 수 있도록 정리한 가이드입니다.

1. 사전 준비 — Node.js와 패키지 매니저

Astro는 Node.js 18.20.8 이상 또는 20.3.0 이상, 22.0.0 이상을 권장합니다. 2026년 기준 가장 안정적인 LTS는 Node.js 22.x 입니다.

Node.js 버전 확인

터미널을 열고 아래 명령으로 현재 버전을 확인합니다.

node -v
# v22.12.0  ← 이런 식으로 출력되면 OK
npm -v
# 10.x.x   ← 함께 설치되어 있어야 함

설치되어 있지 않거나 버전이 낮다면 nodejs.org 에서 LTS 버전을 받거나, nvm 으로 설치합니다.

# macOS / Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
nvm use 22

# Windows
# https://github.com/coreybutler/nvm-windows/releases

패키지 매니저 선택

패키지 매니저	장점	단점	추천 대상
npm	Node 기본 동봉, 설정 불필요	설치 속도 보통	입문자, 기본 권장
pnpm	빠르고 디스크 절약	별도 설치 필요	다중 프로젝트
yarn	안정적, 잘 알려져 있음	최신 기능 도입 느림	기존 yarn 사용자
bun	매우 빠른 설치·실행	일부 생태계 호환 이슈	실험적 사용자

본 가이드는 npm 기준으로 설명합니다. 다른 매니저를 쓴다면 npm 부분을 pnpm / yarn / bun 으로 바꾸어 실행하면 됩니다.

2. Astro 프로젝트 생성

Astro는 공식 CLI인 create astro 한 줄로 프로젝트가 만들어집니다.

# 빈 디렉터리에서 실행
npm create astro@latest

실행하면 다음과 같은 질문을 차례대로 받습니다.

질문	권장 응답	설명
Where should we create your project?	`./my-blog`	프로젝트 폴더 이름
How would you like to start your project?	`Use blog template`	블로그 시작용 템플릿
Install dependencies?	`Yes`	`npm install` 자동 실행
Initialize a new git repository?	`Yes`	Git 저장소 초기화
Do you plan to write TypeScript?	`Yes`	타입 안정성 확보
How strict should TypeScript be?	`Strict`	실수 줄이고 SEO 메타까지 안전

성공적으로 끝나면 다음 메시지를 볼 수 있습니다.

✔ Project initialized!
Next steps:
  cd my-blog
  npm run dev

3. 프로젝트 구조 이해

생성된 my-blog 디렉터리는 다음과 같은 구조를 가집니다.

my-blog/
├─ public/             # 정적 파일 (favicon, robots.txt, 이미지 등)
├─ src/
│  ├─ assets/          # 빌드 시 최적화되는 이미지
│  ├─ components/      # 재사용 컴포넌트 (.astro)
│  ├─ content/         # Markdown / MDX 글 (Content Collections)
│  │  └─ blog/
│  ├─ layouts/         # 페이지 레이아웃
│  ├─ pages/           # 라우팅 단위 페이지
│  │  ├─ index.astro
│  │  └─ blog/[...slug].astro
│  └─ styles/          # 전역 스타일
├─ astro.config.mjs    # Astro 설정
├─ tsconfig.json
└─ package.json

꼭 알아야 할 4가지

폴더/파일	역할	자주 수정하나요?
`src/pages/`	URL과 1:1 매핑되는 페이지	★★★
`src/content/blog/`	글 한 편 = 마크다운 파일 한 개	★★★★★
`src/components/`	Header, Footer, Card 등 재사용 UI	★★★
`astro.config.mjs`	사이트 URL, integrations(Tailwind 등) 설정	★★

4. 개발 서버 실행 및 동작 확인

프로젝트 폴더로 이동해 개발 서버를 실행합니다.

cd my-blog
npm run dev

정상이라면 다음과 같은 출력이 나타납니다.

  astro  v5.x.x ready in 320 ms

  ┃ Local    http://localhost:4321/
  ┃ Network  use --host to expose

브라우저에서 http://localhost:4321 에 접속해 다음 4가지를 확인합니다.

✅ 동작 확인 체크리스트

항목	확인 방법	예상 결과
홈페이지 렌더링	`/` 접속	템플릿 첫 화면 표시
블로그 목록	`/blog` 접속	샘플 글 리스트 표시
개별 글 상세	목록에서 글 클릭	본문·메타 정보 표시
Hot Reload(HMR)	마크다운 파일 수정 후 저장	새로고침 없이 반영

이 4가지가 모두 정상이면 로컬 설치 단계는 완료입니다.

5. 블로그 글 추가하기 (Content Collections)

Astro의 강력함은 src/content/blog/ 폴더에 마크다운 파일만 던져 넣으면 자동으로 글이 생긴다는 점입니다.

새 글 만들기

src/content/blog/hello-astro.md 파일을 만들고 다음 내용을 붙여 넣습니다.

---
title: '첫 번째 Astro 글'
description: 'Astro 블로그에서 처음으로 발행하는 글입니다.'
pubDate: 2026-05-20
heroImage: '../../assets/blog-placeholder-1.jpg'
---

안녕하세요! 이 글은 Astro 블로그의 첫 글입니다.

## 소제목

- 마크다운 문법 그대로 사용 가능
- 코드 블록, 이미지, 표 모두 지원

저장한 뒤 http://localhost:4321/blog/hello-astro 로 접속하면 글이 즉시 표시됩니다.

Frontmatter 스키마 핵심 필드

필드	타입	필수	설명
`title`	string	✅	글 제목 — `<title>` 태그에 사용
`description`	string	✅	메타 description, SNS 미리보기
`pubDate`	date	✅	발행일
`updatedDate`	date	❌	수정일
`heroImage`	image	❌	대표 이미지 (상대 경로)
`tags`	array	❌	태그 목록
`draft`	boolean	❌	`true`면 빌드에서 제외

Frontmatter 스키마는 src/content.config.ts 에서 정의되며, 타입이 맞지 않으면 빌드 시점에 즉시 에러가 납니다. 이는 오타를 미리 잡아주는 장점입니다.

6. 프로덕션 빌드 검증

개발 서버가 잘 떴다고 끝이 아닙니다. 실제 배포되는 산출물은 npm run build 로 생성되는 정적 파일들이며, 이 단계에서 에러가 나는 경우가 가장 많습니다.

npm run build

성공 시 다음과 같이 출력됩니다.

✓ Completed in 4.21s.

building client (vite)
✓ 12 page(s) built in 1.83s
Complete!

생성된 결과물은 dist/ 폴더에 있으며, 정적 미리보기는 다음 명령으로 확인합니다.

npm run preview
# http://localhost:4321 에서 빌드 결과를 그대로 확인

빌드 단계에서 자주 만나는 경고와 의미

메시지 패턴	의미	대응
`Missing field "description" in frontmatter`	필수 필드 누락	마크다운 frontmatter 보강
`Cannot find module './...'`	이미지/모듈 경로 오타	상대 경로 다시 확인
`Hydration mismatch`	클라이언트/서버 렌더 결과 불일치	`client:load` 사용 위치 점검
`Sitemap: 0 pages`	사이트맵에 글이 안 잡힘	`site` 설정과 글 `draft: false` 확인

7. 배포 전 최종 체크리스트

빌드까지 성공했다면 배포 전에 다음 항목을 한 번 더 확인하세요. SEO와 첫인상이 여기서 갈립니다.

🔍 SEO·메타 체크

astro.config.mjs의 site가 실제 도메인으로 설정되었는가?
모든 글에 title / description / pubDate 가 채워져 있는가?
OpenGraph 이미지(heroImage) 가 글마다 지정되어 있는가?
/sitemap-index.xml 이 정상 생성되는가? (빌드 후 dist/ 확인)
/rss.xml 이 정상 생성되는가?

⚡ 성능 체크

Lighthouse 점수 95+ (Performance / SEO / Best Practices)
이미지 최적화: src/assets/ 사용 + <Image /> 컴포넌트
폰트 최적화: font-display: swap 또는 사전 로드
불필요한 JS 미사용: client:* 지시어 최소화

🌐 호스팅 연결

Cloudflare Pages / Vercel / Netlify 중 하나 선택
GitHub 저장소 와 연결, push 시 자동 배포 확인
빌드 명령 npm run build, 출력 폴더 dist 로 설정

8. 자주 발생하는 오류와 해결법

증상	원인	해결
`npm create astro@latest` 가 멈춤	네트워크/방화벽	VPN/사내망 해제 후 재시도, `--use-npm` 옵션 명시
`EACCES: permission denied`	글로벌 설치 권한 문제	`sudo` 대신 nvm으로 Node 재설치
`Port 4321 is in use`	다른 dev 서버가 점유	`npm run dev -- --port 4322` 로 포트 변경
마크다운이 안 보임	`draft: true` 또는 파일명 오타	frontmatter와 파일명 점검
이미지가 깨짐	`public/` 경로와 `src/assets/` 경로 혼동	글 내부 상대 경로는 `../../assets/...`
빌드 후 한국어 깨짐	메타 charset 누락	`<meta charset="utf-8">` 확인 (기본 레이아웃에 있음)
Cloudflare 배포 실패 (`Node version`)	빌드 환경 Node 버전이 낮음	Pages 환경변수에 `NODE_VERSION=22` 추가

FAQ

Q1. Astro 블로그 설치에 얼마나 걸리나요?

Node.js 가 이미 설치되어 있다면 npm create astro@latest 부터 첫 페이지 확인까지 보통 5~10분 안에 끝납니다.

Q2. Windows에서도 동일하게 동작하나요?

네. 단 WSL2 또는 PowerShell 사용을 권장합니다. CMD에서는 일부 컬러/이모지 출력이 깨질 수 있지만 동작에는 문제가 없습니다.

Q3. 기존 템플릿을 안 쓰고 빈 프로젝트로 시작해도 되나요?

가능합니다. 그러나 블로그 기능(콘텐츠 컬렉션, RSS, 사이트맵) 을 직접 구성해야 하므로, 처음에는 공식 blog 템플릿으로 시작한 뒤 점진적으로 커스터마이즈하는 것이 빠릅니다.

Q4. `npm run dev` 가 잘 되는데 `npm run build` 만 실패합니다.

대부분 frontmatter 누락, 이미지 경로 오타, TypeScript 타입 에러 셋 중 하나입니다. 에러 메시지에 표시된 파일을 먼저 열어 보세요.

Q5. 설치 후 가장 먼저 해야 할 커스터마이징은 무엇인가요?

src/consts.ts 또는 astro.config.mjs 의 사이트 제목·URL 변경
public/favicon.svg 교체
src/components/Header.astro 의 메뉴 손보기
첫 글 작성

이 4가지를 마치면 “내 블로그” 라고 부를 수 있는 최소 상태가 됩니다.

Q6. 무료로 배포까지 끝낼 수 있나요?

네. GitHub(저장소 무료) + Cloudflare Pages(트래픽 무제한 무료) 조합이면 도메인 비용을 제외하고 0원으로 운영 가능합니다.

요약

사전 준비: Node.js 22.x + npm 확인.
설치: npm create astro@latest → blog 템플릿 선택 → npm install.
동작 확인: npm run dev 후 홈/블로그/상세 페이지 4가지 항목 점검.
빌드 검증: npm run build 와 npm run preview 로 실제 산출물 확인.
배포 전: SEO·성능·호스팅 체크리스트 통과 후 push.

설치는 5분, 검증은 10분. 이 글의 체크리스트를 그대로 따라가면 첫 배포까지 막힘없이 도달할 수 있습니다. 다음 글에서는 Cloudflare Pages 연결과 커스텀 도메인 적용 방법을 이어서 다루겠습니다.

목차