콘텐츠로 이동

Astro + Vercel 배포 가이드

실제 sigil-css-guide 프로젝트를 배포하면서 배운 내용 정리.

핵심 교훈

Vercel에 빈 프로젝트를 먼저 배포하지 마라. 코드(Astro 등)가 준비된 후에 Import해야 프레임워크 자동 감지 + 웹훅이 제대로 설정된다.

잘못된 순서 (삽질함)

1. GitHub에 빈 repo push (기획문서만)
2. Vercel에서 Import → Framework: Other로 배포  ← 여기서 꼬임
3. Astro 코드 추가 후 push
4. Vercel이 새 push를 감지 못함 (웹훅 안 먹음)
5. Settings에서 Framework를 Astro로 변경해도 기존 배포만 Redeploy됨
6. 결국 프로젝트 삭제 후 재생성

올바른 순서

1. 로컬에서 Astro 프로젝트 세팅 완료
2. GitHub에 push
3. Vercel에서 Import → Astro 자동 감지 → Deploy
4. 이후 push할 때마다 자동 빌드 + 배포

세팅 과정 (정상 루트)

1. Astro 프로젝트 생성

# 빈 폴더에서
npm create astro@latest . -- --template minimal --install --no-git --typescript strictest

# 이미 파일이 있는 폴더면 임시 폴더에 만들고 옮기기
mkdir _temp && cd _temp
npm create astro@latest . -- --template minimal --install --no-git --typescript strictest --yes
# 필요한 파일 복사 후 _temp 삭제

2. Vercel 어댑터 추가

npx astro add vercel --yes
→ astro.config.mjs에 자동으로 adapter: vercel() 추가됨 → .gitignore에 .vercel 추가됨

3. 로컬 빌드 테스트

npm run build
→ 성공하면 dist/ 폴더 생성

4. GitHub에 push

git init
git add -A
git commit -m "init: 프로젝트 초기 세팅"
git remote add origin https://github.com/유저/레포.git
git branch -M main
git push -u origin main

5. Vercel에서 Import

  1. vercel.com → Add New → Project
  2. GitHub repo 선택
  3. Framework Preset: Astro (자동 감지되어야 함)
  4. Deploy 클릭
  5. 1~2분 후 사이트 URL 확인

6. 이후 업데이트

# 코드 수정 후
git add . && git commit -m "메시지" && git push
# → Vercel 자동 빌드 + 배포 (약 30초~1분)

프로젝트 구조 (Astro 기본)

프로젝트/
├── astro.config.mjs     ← Astro 설정 (어댑터 등)
├── package.json
├── tsconfig.json
├── vercel.json          ← (선택) Vercel 빌드 설정 명시
├── public/              ← 정적 파일 (favicon 등)
├── src/
│   ├── layouts/         ← 공통 레이아웃
│   ├── components/      ← 재사용 컴포넌트
│   ├── pages/           ← 페이지 (URL 자동 매핑)
│   ├── styles/          ← CSS
│   └── content/         ← 마크다운 콘텐츠
└── dist/                ← 빌드 결과 (gitignore)

자주 쓰는 명령어

명령어 설명
npm run dev 로컬 개발 서버 (localhost:4321)
npm run build 빌드 (배포 전 테스트)
npm run preview 빌드 결과 미리보기
npx astro add [패키지] Astro 통합 추가

트러블슈팅

⚠️ Vercel에서 push 감지 안 됨 (가장 흔한 문제!)

1순위 확인: Git 이메일 불일치 

git config user.email   # 이 이메일이 Vercel 계정 이메일과 같은지 확인!
- Vercel Hobby(무료) 플랜: 커밋 이메일 ≠ Vercel 계정 이메일이면 에러 표시 없이 배포를 무시함 - Deploy Hook도, git push도 전부 조용히 실패함 - Vercel 대시보드에는 아무 에러도 안 보임 — 이메일로만 알림이 옴 - 해결: git config user.email "Vercel계정이메일" 후 새 커밋 push

증상 체크리스트: | 증상 | 이메일 문제? | |------|------------| | push해도 새 배포 안 뜸 | ✅ 높음 | | Deploy Hook이 PENDING 후 사라짐 | ✅ 높음 | | Redeploy는 되지만 옛 코드만 반복 | ✅ (Redeploy는 기존 배포 재사용이라 이메일 체크 안 함) | | GitHub Webhooks 페이지가 비어있음 | ❌ 정상임 (GitHub App은 별도 시스템) |

2순위: 빈 프로젝트 먼저 배포 - 원인: 빈 프로젝트 상태에서 먼저 배포해서 프레임워크 감지 실패 - 해결: Vercel 프로젝트 삭제 → 코드 준비된 후 재Import

404 에러

  • 원인: Framework Preset이 Other로 되어있어 빌드를 안 함
  • 해결: Settings → Framework Preset → Astro 선택 → Redeploy

빌드 실패

  • 로컬에서 npm run build 먼저 테스트
  • 에러 메시지 확인 후 수정

이메일 설정 정리

글로벌 git 이메일: mintmaum07@gmail.com  (GitHub hangglwriter / Vercel 계정)
업무용 프로젝트:   skychang44@gmail.com   (별도 GitHub 계정, 해당 프로젝트에서만 설정)
  • 두 이메일은 각각 별도의 GitHub 계정에 연결되어 있어서 하나로 합칠 수 없음
  • 웹 배포 프로젝트는 글로벌(mintmaum07)이 자동 적용 → OK
  • 업무용은 프로젝트 폴더에서 git config user.email "skychang44@gmail.com" 실행

모노레포에서 두 번째 앱 배포하기

하나의 GitHub repo에 여러 앱이 있을 때 (예: apps/ai-prompt, apps/keyword-tool), 각 앱을 별도의 Vercel 프로젝트로 배포하는 방법.

핵심 개념

  • 같은 repo에 Vercel 프로젝트를 여러 개 연결할 수 있음
  • 각 프로젝트에서 Root Directory를 다르게 지정하면 됨
  • push하면 연결된 모든 Vercel 프로젝트가 각자 빌드함

배포 순서

1. Vercel 대시보드 → "Add New Project"
2. 같은 GitHub repo를 다시 Import (중복 OK)
3. 설정 화면에서:
   - Root Directory: apps/새앱이름  ← 이게 핵심!
   - Framework Preset: Astro (자동 감지됨)
   - Build/Output: 기본값 그대로
4. Environment Variables 추가 (앱에서 필요한 API 키 등)
5. Deploy 클릭

주의사항

  • Root Directory 설정을 꼭 바꿔야 함 - 안 바꾸면 repo 루트에서 빌드하려다 실패
  • 환경변수는 프로젝트별로 따로 설정 (ai-prompt에 넣은 키가 keyword-tool에 자동으로 가지 않음)
  • 프로젝트 이름에 하이픈(-)은 OK, 환경변수 Key에는 하이픈 불가 (언더스코어_만)
  • git push 한 번이면 연결된 모든 Vercel 프로젝트가 동시에 배포됨

실제 사례 (winner-writing 모노레포)

GitHub repo: hangglwriter/winner-writing

Vercel 프로젝트 #1: winner-writing
  - Root Directory: apps/ai-prompt
  - URL: winner-writing.vercel.app

Vercel 프로젝트 #2: winner-writing-keword
  - Root Directory: apps/keyword-tool
  - URL: winner-writing-keword.vercel.app
  - 환경변수 6개: NAVER_AD_*, ALADIN_TTB_KEY, NAVER_CLIENT_*

SSR 앱 배포 시 추가 사항

keyword-tool처럼 API 라우트가 있는 SSR 앱은: - astro.config.mjs에 output: 'server' + adapter: vercel() 필요 - API 라우트(src/pages/api/*.ts)가 Vercel Serverless Functions로 자동 변환됨 - 환경변수는 Vercel 대시보드에서 설정해야 서버리스 함수에서 접근 가능

2026-02-26 작성 / 2026-02-26 이메일 트러블슈팅 추가. sigil-css-guide 프로젝트 경험 기반. 2026-03-14 모노레포 두 번째 앱 배포 추가. winner-writing 프로젝트 경험 기반.