Vercel 원클릭 배포: 인증 없는 빠르게 앱 게시
학습 후 할 수 있는 것
- 한 문장으로 Claude에게 프로젝트를 Vercel에 배포하도록 요청, 수동 구성 불필요
- 액세스 가능한 미리보기 링크 및 소유권 이전 링크 획득
- 프로젝트 프레임워크 자동 인식(Next.js, React, Vue, Svelte 등 40+ 개）
- 정적 HTML 웹사이트 처리, 단일 파일 자동 이름 변경 지원
현재 당면한 문제
프로젝트를 다른 사람들과 공유하려 할 때마다 다음을 수행해야 합니다:
- Vercel 웹사이트에 수동 로그인
- 새 프로젝트 생성
- Git 저장소 연결
- 빌드 완료까지 대기
- 긴 URL을 기억하여 다른 사람들과 공유
단순히 데모나 프로토타입 빠르게 보여주고 싶은 경우, 이 단계들은 너무 번거롭습니다.
언제 이 기술 사용
다음 시나리오에 적합합니다:
- 🚀 팀과 공유할 빠른 프로젝트 미리보기 생성
- 📦 고객이나 친구에게 데모 전시
- 🔄 CI/CD에서 자동 미리보기 배포 생성
- 🌐 정적 HTML 페이지 또는 SPA 배포
핵심 아이디어
Vercel Deploy 스킬의 작업 플로우는 매우 간단합니다:
말하기 → Claude 키워드 감지 → 배포 스킬 활성화
↓
프레임워크 유형 감지(package.json에서)
↓
프로젝트 패키징(node_modules 및 .git 제외)
↓
Vercel API에 업로드
↓
두 링크 반환(미리보기 + 소유권 이전)왜 두 링크 필요?
- Preview URL: 즉시 액세스 가능한 미리보기 주소
- Claim URL: 배포를 본인의 Vercel 계정하에 이전
이 설계의 이점: 배포자(Agent)는 본인 계정 권한 필요 없음, 이후 Claim URL을 통해 소유권 획득 가능.
🎒 시작 전 준비
사전 확인
- ✅ Agent Skills 설치 완료
- ✅ 프로젝트 디렉토리 구조 완전(package.json 존재 또는 정적 HTML 프로젝트)
- ✅ Claude.ai 네트워크 권한 구성(claude.ai 사용 시)
네트워크 권한 알림
claude.ai(온라인 버전)을 사용하는 경우, *.vercel.com 도메인 액세스 허용 필요:
- https://claude.ai/settings/capabilities 방문
- 허용 도메인 목록에
*.vercel.com추가 - 설정 저장 후 재시도
배포 실패 시 네트워크 오류 표시되면 이 설정 확인.
따라 해보기
1단계: 프로젝트 디렉토리로 이동
# 프로젝트 디렉토리로 이동
cd /path/to/your/project왜 배포 스크립트는 프로젝트의 package.json 및 소스 파일을 찾아야 하므로, 디렉토리 위치 확인 중요.
2단계: Claude에게 배포 요청
Claude 대화에서 다음을 입력:
Deploy my app to Vercel또한 다음 트리거 단어도 시도해 볼 수 있습니다:
- "Deploy this to production"
- "Deploy and give me a link"
- "Push this live"
- "Create a preview deployment"
3단계: 배포 과정 관찰
다음과 비슷한 출력을 볼 수 있습니다:
Preparing deployment...
Detected framework: nextjs
Creating deployment package...
Deploying...
✓ Deployment successful!
Preview URL: https://skill-deploy-abc123.vercel.app
Claim URL: https://vercel.com/claim-deployment?code=...
View your site at Preview URL.
To transfer this deployment to your Vercel account, visit Claim URL.동시에, Claude는 JSON 형식도 출력합니다(스크립트 구문 분석용):
{
"previewUrl": "https://skill-deploy-abc123.vercel.app",
"claimUrl": "https://vercel.com/claim-deployment?code=...",
"deploymentId": "dpl_...",
"projectId": "prj_..."
}예상 결과:
- 배포 성공 표시 ✓
- 두 URL(preview 및 claim)
- 코드 프로젝트인 경우 감지된 프레임워크 이름 표시
4단계: 미리보기 링크 방문
Preview URL 클릭 시, 웹사이트가 라이브로 올라가는 것을 볼 수 있습니다!
데모나 임시 전시인 경우 작업 완료.
5단계: (선택 사항) 소유권 이전
장기 관리 원할 경우:
- Claim URL 클릭
- Vercel 계정에 로그인
- 이전 확인
- 배포가 이제 본인 계정에 속하며, 계속 편집 및 관리 가능
예상 결과:
- 배포가 본인 Vercel 계정에 표시
- Vercel Dashboard에서 로그, 재배포 등 확인 가능
검사점 ✅
배포 완료 후 다음을 확인:
- [ ] Preview URL 브라우저에서 액세스 가능
- [ ] 페이지 정상 표시(404 또는 빌드 오류 없음)
- [ ] 코드 프로젝트인 경우 프레임워크 감지 올바름(Next.js, Vite 등)
- [ ] 장기 관리 필요한 경우 Claim URL을 통한 소유권 이전 완료
지원 프레임워크
Vercel Deploy 스킬은 40+ 개 프레임워크 자동 감지 가능:
| 카테고리 | 프레임워크(부분 예시) |
|---|---|
| React | Next.js, Gatsby, Create React App, Remix |
| Vue | Nuxt, Vitepress, Vuepress |
| Svelte | SvelteKit, Svelte |
| Angular | Angular, Ionic Angular |
| Node.js 백엔드 | Express, Hono, Fastify, NestJS |
| 빌드 도구 | Vite, Parcel |
| 기타 | Astro, Solid Start, Ember, Astro, Hexo, Eleventy |
프레임워크 감지 원리
스크립트는 package.json을 읽고, dependencies 및 devDependencies의 패키지 이름을 확인합니다.
여러 매치가 존재할 경우, 스크립트는 우선순위로 가장 구체적인 프레임워크 선택(예: Next.js가 일반 React보다 우선).
정적 HTML 프로젝트
프로젝트에 package.json 없는 경우(순수 정적 사이트), 배포 스킬은 지능적으로 처리:
- 자동 감지: 루트 디렉토리의
.html파일 식별 - 이름 변경:
.html파일이 하나만 있고index.html이 아닌 경우, 자동으로index.html로 이름 변경 - 직접 배포: 정적 사이트로 Vercel에 호스팅
예시 시나리오:
my-static-site/
└── demo.html # 자동으로 index.html로 이름 변경배포 후, 미리보기 링크 방문 시 demo.html 내용을 볼 수 있습니다.
일반적인 문제 해결
문제 1: 배포 실패, 네트워크 오류
현상:
Error: Network Egress Error원인: claude.ai 기본 외부 도메인 액세스 차단.
해결 방법:
- https://claude.ai/settings/capabilities 방문
- 허용 도메인 목록에
*.vercel.com추가 - 재배포
문제 2: 프레임워크 감지 부정확
현상:
Detected framework: vite
# 하지만 기대하는 것은 nextjs원인: 스크립트는 의존성 우선순위로 매칭하므로, vite 감지 후 정지할 수 있음.
해결 방법:
package.json의존성 순서 확인- 배포에 영향 없는 경우 무시(Vercel 자동 빌드)
- 프로젝트 정상 배포 가능, 다만 기본 Vite 구성 사용 가능
문제 3: 정적 웹사이트 404
현상: 단일 .html 파일 배포 후 방문 시 404.
해결 방법: HTML 파일이 프로젝트 루트에 있는지 확인. 파일이 하위 디렉토리에 있는 경우 Vercel 기본적으로 루트 경로로 라우팅하지 않음.
올바른 구조:
project/
└── my-site.html # 루트 디렉토리의 단일 파일, 자동으로 index.html로 이름 변경잘못된 구조:
project/
└── dist/
└── my-site.html # 자동 이름 변경 안 됨, 방문 시 404문제 4: 배포 성공하지만 페이지 오류
현상: 배포 성공하지만 페이지 방문 시 빌드 오류 또는 런타임 오류 표시.
해결 방법:
- 로컬에서
npm run build실행하여 통과 여부 확인 - 배포 로그 확인(소유권 이전 완료된 경우)
- 환경 변수 확인(프로젝트가
.env의존 시)
자동 제외 파일
배포 스크립트는 자동으로 다음을 제외:
node_modules/(의존성 업로드 방지).git/(버전 기록 업로드 방지)
프로젝트에서 다른 파일(예: .env) 제외 필요 시, 수동 패키징 시 처리.
고급 사용법
배포 경로 지정
다른 디렉토리 배포 지정도 가능:
Deploy project at ./my-appClaude는 해당 경로로 배포합니다.
기존 tarball에서 배포
이미 패키징된 .tgz 파일 있는 경우:
Deploy /path/to/project.tgz to Vercel스크립트는 기존 압축 패키지를 직접 업로드하고, 패키징 단계 건너뜀.
이 과정 요약
Vercel Deploy 스킬은 배포를 전례 없이 간단하게 만듭니다:
핵심 가치:
- ✅ 한 문장으로 배포 완료, 수동 구성 불필요
- ✅ 자동 프레임워크 감지, 40+ 개 기술 스택 지원
- ✅ 인증 없는 배포, 보안성 높음
- ✅ 미리보기 링크 + 소유권 이전 링크 반환
적합 시나리오:
- 🚀 데모나 프로토타입 빠르게 공유
- 📦 팀 내부 미리보기
- 🔄 자동화 CI/CD 플로우
- 🌐 정적 웹사이트 호스팅
다음 단계: 스킬 작동 원리 심층 이해를 원할 경우, React 성능 최적화 베스트 프랙티스 또는 사용자 정의 스킬 개발 학습.
다음 과정 예고
다음 과정에서는 **React/Next.js 성능 최적화 베스트 프랙티스**을 학습합니다.
배우게 될 것:
- 57개 React 성능 최적화 규칙
- 워터폴 제거, 번들 크기 최적화 방법
- Agent가 코드를 자동으로 검사하고 수정 제안을 제공하는 방법
부록: 소스 참고
클릭하여 소스 코드 위치 펼치기
업데이트 날짜: 2026-01-25
| 기능 | 파일 경로 | 행번호 |
|---|---|---|
| 배포 스크립트 진입점 | skills/claude.ai/vercel-deploy-claimable/scripts/deploy.sh | 1-250 |
| 프레임워크 감지 로직 | deploy.sh | 12-156 |
| 패키징 및 API 업로드 | deploy.sh | 208-222 |
| 정적 HTML 이름 변경 | deploy.sh | 192-205 |
| 스킬 정의 문서 | skills/claude.ai/vercel-deploy-claimable/SKILL.md | 1-113 |
| 네트워크 오류 해결 | SKILL.md | 102-112 |
핵심 상수:
DEPLOY_ENDPOINT = "https://claude-skills-deploy.vercel.com/api/deploy": Vercel 배포 API 엔드포인트
핵심 함수:
detect_framework(): package.json에서 40+ 개 프레임워크 감지
지원 프레임워크 감지(우선순위별):
- React 클래스: Next.js, Gatsby, Remix, React Router
- Vue 클래스: Nuxt, Vitepress, Vuepress
- Svelte 클래스: SvelteKit, Svelte
- 기타: Astro, Angular, Express, Hono, Vite, Parcel 등