02. Astro 프로젝트 생성·실행·수정

“비어있는 캔버스 vs 미리 짜인 템플릿. 우린 후자로 시작한다.”

---

이것을 왜 배우는가?

Astro 프로젝트를 처음부터 빈 폴더로 만들 수도 있지만, 공식 블로그 템플릿을 사용하면 다음이 자동으로 셋업됩니다.

자동 셋업되는 것	직접 만들면 걸리는 시간
블로그 메인 페이지 (글 목록)	2~4시간
글 상세 페이지	2~3시간
About 페이지	30분
RSS 피드 (구독 기능)	1시간
사이트맵 (검색 엔진용)	30분
SEO 메타 태그	1시간
마크다운 글 처리 시스템	2시간
반응형 디자인 (모바일 대응)	2~3시간

→ 템플릿 사용 시간: 5분. 직접 만들면 10시간+. 시간 아끼려고 템플릿 씁니다.

이 단계를 끝내면 본인 컴퓨터에서 블로그가 동작하는 걸 볼 수 있습니다 (아직 인터넷에 안 올라감).

---

전체 흐름 미리보기

[현재 상태]
빈 폴더, 아무것도 없음
        ↓
[Step 1] npm create astro@latest
        ↓
[새 폴더 생성: my-blog/]
필요한 파일·폴더 자동 생성
디펜던시 (필요한 패키지) 설치
        ↓
[Step 2] cd my-blog && npm run dev
        ↓
[로컬 서버 시작]
http://localhost:4321 에서 사이트 확인
        ↓
[Step 3] 본인 정보로 수정
- 사이트 제목·설명
- About 페이지
- 샘플 글 정리
        ↓
[완료]
본인 컴퓨터에서 블로그 동작 확인

로컬 서버: 본인 컴퓨터에서만 보이는 사이트. 인터넷에 안 올라감. 개발 중 미리보기 용도.

---

Step 1. Astro 프로젝트 생성

폴더 위치 선택

먼저 어디에 프로젝트를 만들지 결정합니다. 일반적으로 본인 홈 폴더 아래 code/ 같은 폴더를 만들어 그 안에 둡니다.

추천 위치:

# Mac
~/code/                  # 또는 ~/Documents/code/

# Windows
C:\Users\본인이름\code\    # 또는 Documents\code\

⚠️ 피해야 할 위치:

• iCloud Drive 동기화되는 폴더 (Mac) — 동기화 충돌 가능
• OneDrive 동기화 폴더 (Windows) — 동기화 충돌
• 한글이 들어간 경로 (/사용자/김민수/) — 일부 도구 호환성 문제

폴더 만들기

터미널 열고:

# Mac
mkdir -p ~/code
cd ~/code

# Windows (PowerShell)
mkdir C:\Users\$env:USERNAME\code
cd C:\Users\$env:USERNAME\code

mkdir = “make directory”의 줄임. 폴더 만들기. cd = “change directory”의 줄임. 폴더 이동.

Astro 생성 명령어 실행

npm create astro@latest my-blog

npm create = npm 패키지 생성 명령어. astro@latest라는 패키지를 사용해서 my-blog라는 폴더를 만든다는 뜻. @latest = 최신 버전 사용. 2026년 4월 현재 Astro 5.x 시리즈.

🟡 INFERRED 버전 정보 (2026년 4월 시점):

• Astro 5.x — 안정 버전 (2024년 11월 출시)
• Astro 6.x — 출시됐을 가능성 있음. @latest는 자동으로 최신 가져옴

⚠️ 이름 정할 때 주의: my-blog 자리에 본인이 원하는 폴더 이름. 영문·하이픈만 권장. 한글·공백·특수문자 X.

질문에 답하기

명령어 실행하면 질문이 순서대로 나옵니다:

◆ Where should we create your new project?
│  ./my-blog
└

◆ How would you like to start your new project?
│  ● Use blog template       ← 이거 선택 (방향키 + Enter)
│  ○ Use minimal (empty) template
│  ○ Use a different template

◆ Do you plan to write TypeScript?
│  ● Yes                     ← Yes 권장
│  ○ No

◆ How strict should TypeScript be?
│  ● Strict (recommended)    ← 기본값
│  ○ Strictest
│  ○ Relaxed

◆ Install dependencies?
│  ● Yes                     ← Yes 필수
│  ○ No

◆ Initialize a new git repository?
│  ● Yes                     ← Yes 권장
│  ○ No

TypeScript: 자바스크립트 + 타입 검사. 처음엔 Yes 해도 코드 거의 안 만지므로 부담 없음. 나중에 코드 추가할 때 도움됨. dependencies: Astro가 동작하기 위해 필요한 다른 패키지들. Yes 필수. git repository: Git 저장소로 초기화. Yes 하면 다음 단계 (GitHub) 더 쉬움.

설치가 끝나면 이런 메시지가 나옵니다:

✔ Project initialized!
✔ Dependencies installed
✔ Git initialized

🚀 Next steps:
  cd my-blog
  npm run dev

✅ 여기까지 성공하면 다음으로.

❌ 만약 에러:

• npm: command not found → Node.js 재설치 (01번 가이드)
• EACCES: permission denied → Mac에서 sudo npm create... 시도 (단, 권한 문제는 보통 다른 방법이 더 깔끔. AI에 물어보세요)

---

Step 2. 로컬 서버 실행

명령어 실행

cd my-blog       # my-blog 폴더로 이동
npm run dev      # 로컬 서버 시작

npm run dev = “development(개발)” 모드로 서버 실행. 본인 컴퓨터에서만 보이는 사이트 띄움.

성공하면 이런 메시지:

🚀  astro  v5.x.x ready in 800 ms

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

브라우저에서 확인

크롬·사파리·엣지 등 브라우저 주소창에:

http://localhost:4321

→ Astro 기본 블로그 템플릿이 보입니다. 메인 페이지에 샘플 글 3개 정도 나옴.

✅ 사이트 보이면 성공. 이제 본인 컴퓨터에서 블로그가 동작합니다.

⚠️ 이 사이트는 아직 인터넷에 없습니다. 본인 컴퓨터에서만 보이는 미리보기. 인터넷 배포는 다음 가이드(03)에서.

서버 끄기

터미널에서 Ctrl + C 누르면 서버 멈춤. 다시 켜려면 npm run dev 재실행.

⚠️ 서버 켜둔 채로 다음 단계 진행: 파일 수정하면 사이트 자동 새로고침됩니다. 매번 끄고 켤 필요 없음.

---

Step 3. 폴더 구조 이해

프로젝트 폴더 안 살펴보기

VS Code 또는 Cursor 열고 File → Open Folder 로 my-blog 폴더 선택. 좌측에 폴더 트리가 보입니다.

my-blog/
├── public/                  ← 정적 파일 (favicon 등)
│   └── favicon.svg
│
├── src/                     ← ★ 본인이 주로 만지는 곳
│   ├── components/          ← 재사용 가능한 부품 (헤더·푸터 등)
│   │   ├── Header.astro
│   │   ├── Footer.astro
│   │   ├── BaseHead.astro   ← 메타 태그 (SEO 등)
│   │   └── ...
│   │
│   ├── content/             ← ★★ 본인이 글 쓰는 곳
│   │   └── blog/            ← 글 마크다운 파일들
│   │       ├── first-post.md
│   │       ├── second-post.md
│   │       └── ...
│   │
│   ├── layouts/             ← 페이지 골격 템플릿
│   │   └── BlogPost.astro   ← 글 페이지 모양
│   │
│   ├── pages/               ← URL 페이지들
│   │   ├── index.astro      ← 메인 페이지 (yourname.com/)
│   │   ├── about.astro      ← About 페이지 (/about)
│   │   └── blog/
│   │       ├── index.astro  ← 글 목록 (/blog)
│   │       └── [...slug].astro  ← 개별 글 (/blog/first-post)
│   │
│   ├── consts.ts            ← ★ 사이트 제목·설명 설정
│   ├── content.config.ts    ← 콘텐츠 컬렉션 설정
│   └── styles/
│       └── global.css       ← 전역 스타일
│
├── astro.config.mjs         ← Astro 설정 파일
├── package.json             ← 프로젝트 정보·의존 패키지 목록
├── tsconfig.json            ← TypeScript 설정
└── README.md                ← 프로젝트 설명

★ 표시: 본인이 자주 만지는 파일. ★★ 표시: 매일 글 쓸 때 만지는 폴더.

어디서 무엇을 하는지 정리

무엇을 하고 싶은가	어디를 만지는가
사이트 제목·설명 변경	src/consts.ts
메인 페이지 디자인	src/pages/index.astro
About 페이지 내용	src/pages/about.astro
글 추가	src/content/blog/새글.md
메뉴 항목 변경	src/components/Header.astro
푸터(하단) 변경	src/components/Footer.astro
색깔·폰트 변경	src/styles/global.css
글 페이지 디자인	src/layouts/BlogPost.astro

→ 처음엔 위 5~6개만 만지면 충분합니다.

---

Step 4. 본인 정보로 수정

4-1. 사이트 제목·설명 (src/consts.ts)

src/consts.ts 파일을 엽니다. 기본 내용:

// 사이트 전체에서 사용되는 상수들

// 사이트 제목 (브라우저 탭, 메타 태그에 표시)
export const SITE_TITLE = 'Astro Blog';

// 사이트 설명 (검색 결과·SNS 공유 시 표시)
export const SITE_DESCRIPTION = 'Welcome to my website!';

수정:

// 본인 이름 또는 사이트 이름
export const SITE_TITLE = '김민수의 블로그';

// 무엇을 다루는 사이트인지 한 줄 소개
export const SITE_DESCRIPTION = '1인 개발자의 빌딩 일지와 배움 기록';

export const = 다른 파일에서 가져다 쓸 수 있게 내보내는 상수. 의미는 “외부 공개 + 변하지 않는 값”.

저장하면 (Cmd+S / Ctrl+S) 브라우저 자동 새로고침. 사이트 제목 바뀐 거 확인.

4-2. About 페이지 (src/pages/about.astro)

기본 내용:

---
import Layout from '../layouts/BlogPost.astro';
---

<Layout
	title="About Me"
	description="Lorem ipsum dolor sit amet"
	pubDate={new Date('August 08 2021')}
>
	<p>
		Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed posuere interdum sem...
	</p>
</Layout>

Layout 컴포넌트: 페이지의 골격. 헤더·푸터 등 공통 부분 자동 적용. --- 사이의 코드: 자바스크립트/TypeScript 영역 (Astro가 처리할 코드). --- 아래: HTML 영역 (실제 표시될 내용).

본인 정보로 수정:

---
import Layout from '../layouts/BlogPost.astro';
---

<Layout
	title="About Me"
	description="개발자 김민수입니다"
	pubDate={new Date('April 29 2026')}
>
	<p>
		안녕하세요. 1인 개발자 김민수입니다.
		끌리는 것들을 만들고 그 과정을 기록합니다.
	</p>

	<h2>관심사</h2>
	<ul>
		<li>AI 활용 빌딩</li>
		<li>외국인을 위한 한국어 학습 도구</li>
		<li>개발자 생산성 도구</li>
	</ul>

	<h2>연락</h2>
	<p>
		<a href="https://github.com/본인아이디">GitHub</a> ·
		<a href="mailto:your@email.com">Email</a>
	</p>
</Layout>

⚠️ HTML 태그 처음 보면: <p>본문</p>, <h2>제목</h2>, <a href="주소">링크</a> 정도만 알면 됨. 더 필요하면 AI에 “이 부분에 ___ 추가해줘” 물어보세요.

저장하면 자동 새로고침. http://localhost:4321/about 에서 확인.

4-3. 메인 페이지 (src/pages/index.astro)

기본 내용은 보통 사이트 소개 + 최근 글 목록. 처음엔 그대로 두고 글 추가에 집중하세요.

수정하고 싶다면:

• <h1>제목</h1> 같은 부분의 텍스트만 바꾸기
• 큰 변경은 AI에게 “메인 페이지를 ___ 스타일로 바꿔줘” 요청

4-4. 샘플 글 정리 (src/content/blog/)

기본 템플릿엔 샘플 글 4~5개가 있습니다. 두 가지 옵션:

옵션 A: 다 삭제하고 본인 글만

# 터미널에서
cd src/content/blog
rm *.md

옵션 B: 1~2개 남겨두고 참고용으로

• 마크다운 사용법 참고하기 위해 1개 정도 남겨둠
• 나중에 본인 글 추가하면 자동으로 목록에 함께 표시됨

→ 권장: 옵션 B. 처음엔 마크다운 문법 헷갈리니 샘플 보면서 따라쓰는 게 편함.

---

Step 5. 디자인 변경 (선택)

기본 디자인이 마음에 안 들면 두 가지 방법:

방법 1: AI에게 요청 (가장 쉬움)

Cursor 또는 Claude/ChatGPT에:

"src/styles/global.css 파일의 색깔을 다크 테마로 바꿔줘.
배경은 검정, 글자는 흰색, 강조는 파란색으로."

→ AI가 코드 수정해줌. 그대로 적용.

방법 2: 다른 템플릿 적용

https://astro.build/themes 들어가서 마음에 드는 블로그 템플릿 다운로드 후 코드 가져오기. 단 시간 더 걸림.

⚠️ 디자인에 1주일 쓰지 마세요. 글 1편이 디자인 1주일보다 100배 가치 있습니다. 일단 기본 디자인으로 글부터 쓰세요.

---

정리 및 체크리스트

□ npm create astro@latest my-blog 명령어 성공적으로 실행
□ blog template 선택, dependencies 설치 완료
□ npm run dev 실행 후 http://localhost:4321에서 사이트 확인
□ VS Code/Cursor에서 my-blog 폴더 열림
□ src/consts.ts에 본인 사이트 제목·설명 입력
□ src/pages/about.astro에 본인 소개 작성
□ src/content/blog/ 안의 샘플 글 정리
□ 브라우저에서 변경 사항 자동 반영되는 것 확인

---

흔한 실수 모음

실수	결과	해결
Use blog template 대신 minimal 선택	처음부터 직접 다 만들어야 함	다시 npm create로 새 폴더 만들기
Yes/No 대신 Y/N만 입력	일부 시스템에서 인식 안 됨	풀 단어 입력 (Yes/No)
Korean 폴더 경로 사용	일부 빌드 에러	영문 경로로 옮기기
서버 끄지 않은 채 폴더 이동	서버 동작 멈춤	Ctrl+C로 끄고 다시 npm run dev
변경 사항이 브라우저에 반영 안 됨	캐시 문제	브라우저 강제 새로고침 (Cmd+Shift+R / Ctrl+Shift+R)
.astro 파일 안의 --- 영역 헷갈림	문법 에러	위쪽은 JS, 아래쪽은 HTML로 기억

---

💡 핵심 포인트

이 단계의 핵심: 공식 템플릿으로 빠르게 시작 → 본인 정보만 수정 → 글 쓸 준비 완료.

디자인 완벽화에 빠지지 마세요. 다음 단계 (인터넷 배포)로 가서 글부터 쓰는 게 우선입니다.

---

다음 단계

03-deploy.md — GitHub 저장소 만들고 Cloudflare Pages에 배포해서 인터넷에 사이트 띄우기