Biz Deploy Vercel — 웹사이트를 Vercel에 안전하게, 한 번의 명령으로은(는) 무엇을 하나요?
이 스킬은 로컬 프로젝트 폴더(React / Next.js / Vite / 정적 HTML)를 SSL, CDN, 미리보기 배포가 포함된 라이브 URL로 전환합니다. 목표: DevOps 지식이 없는 개인 개발자/중소기업도 Claude와의 대화만으로 랜딩 페이지를 배포할 수 있도록 돕는 것입니다.
핵심 원칙: Claude가 직접 확인할 수 있는 내용을 사용자에게 묻지 않습니다. 프레임워크를 자동 감지하고, 필요 시
vercel.json을 자동 생성하며, 실제로 수동 개입이 필요한 경우(브라우저 로그인, 사용자 정의 도메인 DNS)에만 멈춥니다.
사용 시기
사용자가 다음을 원할 때:
- 랜딩 페이지/웹사이트를 라이브 URL로 배포하여 공유/테스트/광고 실행
- 코드 수정 후 프로젝트 재배포
- 새 저장소에 Vercel을 처음 설정할 때
- Vercel로 연결할 사용자 정의 도메인 설정
사용하지 말아야 할 시기
- 로컬 빌드만 필요하고 아직 공개하고 싶지 않을 때 → 건너뛰고
npm run build/next dev사용 - Netlify / Cloudflare Pages / AWS에 배포해야 할 때 → 이 스킬은 Vercel 전용입니다.
- 사용자 정의 GitHub Actions를 사용한 복잡한 CI/CD가 필요할 때 → 프로젝트 초기화에는 이 스킬을 사용할 수 있지만, 사용자 정의 워크플로는 사용자가 직접 구성해야 합니다.
- 상태 저장(Node.js 웹소켓, 롱 폴링) 백엔드가 필요할 때 → Vercel 서버리스는 적합하지 않습니다. Railway / Fly.io를 사용하세요.
사용자가 받게 될 결과
- 라이브 URL (
https://<project>.vercel.app형태의 프로덕션 또는 미리보기 URL) - 인스펙트 URL (
https://vercel.com/<account>/<project>/<deployment-id>형태, 로그 확인용) - 링크된 프로젝트(
.vercel/project.json에 저장, gitignore 처리됨) — 다음 배포 시vercel --prod만 실행하면 됩니다. - 사용자가 사용자 정의 도메인을 요청하면 구체적인 DNS 안내(A 레코드 / CNAME)를 제공합니다.
6단계 워크플로우
1단계 — 사전 점검: Vercel CLI / MCP 확인
scripts/check_vercel.sh (또는 이에 상응하는 인라인 명령)을 실행하여 다음 3가지 상태를 확인합니다:
| 확인 항목 | 명령어 | 예상 결과 |
|---|---|---|
| Node.js | node --version | v18+ 또는 v20+ |
| Vercel CLI | vercel --version | 버전 반환 (v32+) |
| Vercel 인증 | vercel whoami | 사용자 이름 반환 |
Node.js가 없는 경우:
- macOS:
brew install node또는 https://nodejs.org 에서 다운로드 안내 - Windows: https://nodejs.org/en/download/ 에서 .msi 설치 프로그램 다운로드 안내
- Linux:
nvm install --lts또는 패키지 매니저 사용 안내 - 스킬을 중단하고 사용자가 설치를 완료했다고 알릴 때까지 기다립니다.
Vercel CLI가 없는 경우:
- 사용 중인 패키지 매니저를 감지합니다(
pnpm,yarn,npm순서로 확인하거나 프로젝트의 lockfile을 읽음). - 전역 설치:
pnpm add -g vercel(사용자가 pnpm을 사용하는 경우)npm install -g vercel(기본값)
vercel --version으로 다시 확인합니다.
Vercel CLI는 있지만 인증되지 않은 경우 (vercel whoami 오류):
vercel login실행 — 이 명령은 브라우저를 열고, 사용자가 클릭하여 확인해야 합니다. 이는 수동 개입이 필요한 과정으로, 건너뛸 수 없습니다.- 사용자에게 안내: "vercel login을 실행했습니다. 브라우저를 열고 확인을 클릭하여 인증해 주세요. 완료되면 'ok'라고 입력해 주세요."
- 중단하고 사용자의 응답을 기다립니다.
사용자가 Vercel MCP를 사용한다고 말한 경우:
- 사용 가능한 MCP 도구를 나열하여 MCP 서버를 확인합니다(
mcp__vercel__*접두사가 붙은 도구). - MCP가 있더라도 실제 배포에는 CLI를 우선 사용합니다(CLI가 파일 업로드에 더 안정적임). 배포 후 프로젝트/도메인/환경 변수 등을 쿼리해야 하는 경우 MCP를 사용합니다.
- 사용자가 MCP 사용을 강제하는 경우: https://vercel.com/docs/mcp 문서에 따라 인증하고 해당 MCP 도구를 사용합니다.
2단계 — 프레임워크 및 프로젝트 구조 감지
프로젝트 루트의 파일을 읽어 프레임워크를 확인합니다:
| 파일 | 프레임워크 |
|---|---|
next.config.js / next.config.mjs / next.config.ts | Next.js |
vite.config.js / vite.config.ts | Vite (React/Vue/Svelte) |
package.json에 "react-scripts" 포함 | Create React App |
package.json에 "astro" 포함 | Astro |
package.json에 "@remix-run/dev" 포함 | Remix |
index.html + 정적 자산만 있고 package.json 없음 | 정적 HTML |
package.json은 있지만 위 패턴과 일치하지 않음 | 사용자에게 프레임워크를 묻거나 Vercel 자동 감지에 맡깁니다 |
추가 정보 기록:
package.json의 빌드 명령어 (scripts.build)- 출력 디렉토리 (Next:
.next, Vite:dist, CRA:build, 정적:.) - 필수 Node 버전 (
engines.node또는.nvmrc에서)
→ 해당 참조 문서 읽기:
- React/Vite →
references/react-vite.md - Next.js →
references/nextjs.md - 정적 HTML →
references/static-html.md
3단계 — vercel.json 생성 (필요한 경우)
Next.js: Vercel이 완전히 자동 감지하므로, 사용자 정의 헤더/리디렉션이 필요하지 않은 한 vercel.json이 필요 없습니다.
Vite / CRA (SPA 라우팅): 클라이언트 측 라우팅이 작동하려면 모든 경로를 index.html로 재작성하는 vercel.json이 필요합니다:
{
"rewrites": [
{ "source": "/(.*)", "destination": "/index.html" }
]
}
정적 HTML: 일반적으로 필요하지 않습니다. 사이트에 여러 페이지(thank-you.html, privacy.html)가 있으면 재작성이 필요 없습니다. index.html만 있고 JS 라우터가 있는 경우 SPA처럼 재작성이 필요합니다.
보안 헤더 (프로덕션에 권장):
{
"headers": [
{
"source": "/(.*)",
"headers": [
{ "key": "X-Content-Type-Options", "value": "nosniff" },
{ "key": "X-Frame-Options", "value": "DENY" },
{ "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
]
}
]
}
규칙: 사용자가 실제로 필요할 때만 vercel.json을 만듭니다. 불필요한 파일 생성은 저장소에 잡음만 더합니다.
4단계 — 배포 전 점검 목록
vercel을 실행하기 전에 다음을 확인합니다:
-
.gitignore에.vercel/,node_modules/,.env*가 포함되어 있는지 (비밀 키를 커밋하지 않도록 함) - 코드 내 파일 경로가 모두 소문자 + 상대 경로인지 (Linux는 대소문자 구분)
- 하드코딩된
localhostURL이 없는지 - 외부 스크립트/스타일시트가 모두
https://로 시작하는지 - Next.js에 환경 변수가 있는 경우 → 설정해야 할 환경 변수 목록을 준비했는지
-
package.json이 있는 경우 →npm install(또는 이에 상응하는 명령)이 로컬에서 실행 가능한지
명확한 문제(예: HTML에 하드코딩된 localhost)가 발견되면 먼저 수정한 후 배포합니다.
5단계 — 배포
프로젝트 첫 배포 (.vercel/project.json 없음):
vercel --prod --yes
--yes 플래그는 프레임워크 자동 감지로부터 모든 기본 설정을 수락합니다. Vercel은 다음을 수행합니다:
- 범위 확인 (
--yes가 있으면 자동으로 사용자 계정 선택) - 프레임워크 사전 설정 감지
- 빌드 명령어 및 출력 디렉토리 설정
- 코드 푸시, 빌드, 배포
사용자 정의 프로젝트 이름이 필요하거나 사용자가 기존 프로젝트에 연결하려는 경우:
vercel link # 기존 프로젝트에 연결 (대화형)
vercel --prod # 연결 후 배포
미리보기 배포 (프로덕션 아님):
vercel
→ https://<project>-<hash>.vercel.app 형태의 미리보기 URL 반환, 프로덕션 승격 전 테스트용으로 사용합니다.
재배포 (프로젝트가 이미 연결된 경우):
vercel --prod
출력 캡처 — stdout에서 다음을 추출합니다:
Production: https://<project>.vercel.appInspect: https://vercel.com/...
두 URL을 즉시 사용자에게 알립니다.
6단계 — 확인 및 보고
배포 성공 후:
curl -I https://<project>.vercel.app로 라이브 URL에 대한 HTTP 확인 — 상태 200 및 SSL 활성화 확인- 사용자에게 보고 (다음 형식 사용):
## ✅ 배포 성공
**라이브 URL**: https://<project>.vercel.app
**인스펙트 / 로그**: https://vercel.com/<account>/<project>/<deployment-id>
**프레임워크**: <Next.js | Vite | CRA | 정적 HTML>
**빌드 시간**: <X초>
### 다음 배포 시
`vercel --prod` 만 실행하면 됩니다.
### 옵션
- 사용자 정의 도메인 설정 → `setup domain <yourdomain.com>` 이라고 알려주세요.
- 환경 변수 설정 → `add env <KEY>` 라고 알려주세요.
- 로그 보기 → `vercel logs`
- 사용자가 사용자 정의 도메인을 요청하면
references/domains.md를 읽고 DNS를 안내합니다.
예외 상황 및 복구
로컬에서는 잘 되는데 Vercel에서 빌드 실패
일반적인 원인:
- 대소문자 구분:
import './Components/Header'가 Mac에서는 잘 실행되지만 실제 디렉토리가components인 Linux에서는 실패합니다. 수정: 실제 대소문자에 맞게 이름을 바꿉니다. - 종속성 누락: 패키지가
devDependencies에 있지만 런타임에 필요한 경우 →dependencies로 이동합니다. - Node 버전 불일치:
package.json에"engines": { "node": "20.x" }를 추가하거나.nvmrc파일을 만듭니다.
→ vercel logs <deployment-url> 로 로그를 가져와 읽고, 수정한 후 재배포합니다.
잘못된 계정/프로젝트에 연결된 경우
rm -rf .vercel/ 를 실행한 후 vercel --prod --yes 를 다시 실행합니다. 또는 vercel link 를 사용하여 올바른 프로젝트를 선택합니다.
프로덕션 환경 변수
vercel env add <KEY> production
# 프롬프트에 값 붙여넣기
vercel env pull .env.production.local # 필요한 경우 로컬로 가져오기
.env* 파일을 커밋하지 않도록 합니다. 아직 없다면 .gitignore에 추가합니다.
인증 만료
CLI 토큰이 만료될 수 있습니다. vercel whoami가 권한 없음 오류를 표시하면 vercel login 을 다시 실행합니다.
프레임워크별 상세 참조
프로젝트 프레임워크와 일치하는 참조 문서를 읽습니다:
| 프레임워크 | 참조 문서 |
|---|---|
| Next.js (App / Pages 라우터) | references/nextjs.md |
| React (Vite / CRA) | references/react-vite.md |
| 정적 HTML | references/static-html.md |
| 사용자 정의 도메인 + DNS | references/domains.md |
| 오류 및 문제 해결 | references/troubleshooting.md |
원본 참조
- Vercel CLI 문서: https://vercel.com/docs/cli
- Vercel 빌드 설정: https://vercel.com/docs/projects/project-configuration
- Vercel 제한 사항 (무료 요금제): https://vercel.com/docs/limits
- 상태 페이지: https://www.vercel-status.com