Vercel에 배포하기
모든 프로젝트를 Vercel에 배포합니다. 항상 프리뷰(preview)로 배포하며(프로덕션은 사용자가 명시적으로 요청한 경우에만), 사용자가 궁극적으로 프로젝트를 Vercel에 연결하고 깃 푸시로 자동 배포를 사용하는 장기적인 설정을 갖추도록 하는 것이 목표입니다. 아래 모든 방법은 사용자를 그 상태에 더 가깝게 이동시키기 위해 설계되었습니다.
1단계: 프로젝트 상태 확인
네 가지 검사를 모두 실행한 후 사용할 방법을 결정합니다.
# 1. 깃 리모트 확인
git remote get-url origin 2>/dev/null
# 2. Vercel 프로젝트와 로컬 연결 확인 (두 파일 중 하나가 있으면 연결됨)
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
# 3. Vercel CLI 설치 및 인증 확인
vercel whoami 2>/dev/null
# 4. 사용 가능한 팀 목록 확인 (인증된 경우)
vercel teams list --format json 2>/dev/null
팀 선택
사용자가 여러 팀에 속해 있으면 모든 사용 가능한 팀 슬러그를 글머리 기호 목록으로 표시하고 어느 팀에 배포할지 물어봅니다. 사용자가 팀을 선택하면 추가 확인 없이 즉시 다음 단계로 진행합니다.
이후 모든 CLI 명령어(vercel deploy, vercel link, vercel inspect 등)에 --scope를 통해 팀 슬러그를 전달합니다.
vercel deploy [path] -y --no-wait --scope <팀-슬러그>
프로젝트가 이미 연결된 경우(.vercel/project.json 또는 .vercel/repo.json 존재), 해당 파일의 orgId가 팀을 결정하므로 다시 물을 필요가 없습니다. 팀이 하나만 있거나(또는 개인 계정만 있는 경우) 프롬프트를 건너뛰고 바로 사용합니다.
.vercel/ 디렉토리에 대해: 연결된 프로젝트는 다음 중 하나를 가집니다.
.vercel/project.json—vercel link로 생성됨 (단일 프로젝트 연결).projectId와orgId를 포함합니다..vercel/repo.json—vercel link --repo로 생성됨 (리포지토리 기반 연결).orgId,remoteName, 그리고 디렉토리를 Vercel 프로젝트 ID에 매핑하는projects배열을 포함합니다.
두 파일 중 하나라도 있으면 프로젝트가 연결된 것입니다. 둘 다 확인하세요.
연결되지 않은 디렉토리에서 상태 감지를 위해 vercel project inspect, vercel ls, 또는 vercel link를 사용하지 마십시오 — .vercel/ 설정이 없으면 이 명령어들은 대화형 프롬프트를 표시하거나(--yes 옵션으로 조용히 연결을 부작용으로 수행할 수 있음) 안전하지 않습니다. vercel whoami만 어디서나 안전하게 실행할 수 있습니다.
2단계: 배포 방법 선택
연결됨 + 깃 리모트 있음 → Git Push
이것이 이상적인 상태입니다. 프로젝트가 연결되어 있고 깃 통합이 활성화되어 있습니다.
-
푸시하기 전에 사용자에게 물어보십시오. 명시적 승인 없이 푸시하지 마십시오.
이 프로젝트는 Vercel에 깃으로 연결되어 있습니다. 변경 사항을 커밋하고 푸시하여 배포를 트리거할 수 있습니다. 진행할까요? -
커밋 및 푸시:
git add . git commit -m "deploy: <변경 사항 설명>" git pushVercel이 푸시에서 자동으로 빌드합니다. 프로덕션이 아닌 브랜치는 프리뷰 배포를 받고, 프로덕션 브랜치(보통
main)는 프로덕션 배포를 받습니다. -
프리뷰 URL 가져오기. CLI가 인증된 경우:
sleep 5 vercel ls --format jsonJSON 출력에는
deployments배열이 있습니다. 최신 항목의url필드가 프리뷰 URL입니다.CLI가 인증되지 않은 경우, 사용자에게 Vercel 대시보드 또는 깃 제공자의 커밋 상태 확인에서 프리뷰 URL을 확인하라고 알립니다.
연결됨 + 깃 리모트 없음 → vercel deploy
프로젝트는 연결되어 있지만 깃 리포지토리가 없습니다. CLI로 직접 배포합니다.
vercel deploy [path] -y --no-wait
--no-wait를 사용하여 CLI가 빌드가 끝날 때까지 기다리지 않고(빌드는 시간이 걸릴 수 있음) 배포 URL을 즉시 반환하도록 합니다. 그런 다음 다음 명령어로 배포 상태를 확인합니다.
vercel inspect <배포-url>
프로덕션 배포의 경우(사용자가 명시적으로 요청한 경우에만):
vercel deploy [path] --prod -y --no-wait
연결되지 않음 + CLI 인증됨 → 먼저 연결한 후 배포
CLI는 작동하지만 프로젝트가 아직 연결되지 않았습니다. 사용자를 최상의 상태로 만들 기회입니다.
-
사용자에게 어느 팀에 배포할지 물어봅니다. 1단계의 팀 슬러그를 글머리 기호 목록으로 표시합니다. 팀이 하나만 있거나(또는 개인 계정만 있는 경우) 이 단계를 건너뜁니다.
-
팀이 선택되면 바로 연결로 진행합니다. 사용자에게 어떤 일이 일어날지 알리지만 별도 확인을 요청하지는 마십시오.
이 프로젝트를 Vercel의 <팀 이름> 팀에 연결합니다. 이렇게 하면 Vercel 프로젝트가 생성되고 향후 깃 푸시 시 자동 배포가 활성화됩니다. -
깃 리모트가 있으면, 선택한 팀 범위로 리포지토리 기반 연결을 사용합니다.
vercel link --repo --scope <팀-슬러그>이 명령어는 깃 리모트 URL을 읽고 해당 리포지토리에서 배포하는 기존 Vercel 프로젝트와 일치시킵니다.
.vercel/repo.json을 생성합니다. 이는 로컬 폴더 이름과 Vercel 프로젝트 이름이 다를 때 종종 실패하는vercel link(--repo없이)보다 훨씬 더 안정적입니다.깃 리모트가 없으면, 표준 연결로 대체합니다.
vercel link --scope <팀-슬러그>이 명령어는 사용자에게 프로젝트를 선택하거나 생성하라는 프롬프트를 표시합니다.
.vercel/project.json을 생성합니다. -
그런 다음 사용 가능한 최상의 방법으로 배포합니다.
- 깃 리모트가 있으면 → 커밋 및 푸시(위의 Git Push 방법 참조)
- 깃 리모트가 없으면 →
vercel deploy [path] -y --no-wait --scope <팀-슬러그>, 그런 다음vercel inspect <url>로 상태 확인
연결되지 않음 + CLI 인증되지 않음 → 설치, 인증, 연결, 배포
Vercel CLI가 전혀 설정되어 있지 않습니다.
-
CLI 설치(아직 설치되지 않은 경우):
npm install -g vercel -
인증:
vercel login사용자가 브라우저에서 인증을 완료합니다. 로그인이 불가능한 비대화형 환경에서 실행하는 경우, 인증 없는 대체 방법으로 건너뜁니다.
-
어느 팀에 배포할지 물어봅니다 —
vercel teams list --format json의 팀 슬러그를 글머리 기호 목록으로 표시합니다. 팀이 하나만 있거나(개인 계정인 경우) 건너뜁니다. 선택되면 즉시 진행합니다. -
프로젝트를 연결합니다 선택한 팀 범위로(깃 리모트가 있으면
--repo사용, 그렇지 않으면 일반vercel link).vercel link --repo --scope <팀-슬러그> # 깃 리모트가 있는 경우 vercel link --scope <팀-슬러그> # 깃 리모트가 없는 경우 -
배포합니다 사용 가능한 최상의 방법으로(깃 리모트가 있으면 Git Push, 그렇지 않으면
vercel deploy -y --no-wait --scope <팀-슬러그>, 그런 다음vercel inspect <url>로 상태 확인).
인증 없는 대체 방법 — claude.ai 샌드박스
사용 시기: claude.ai 샌드박스에서 CLI를 설치하거나 인증할 수 없는 마지막 수단입니다. 인증이 필요하지 않으며 프리뷰 URL(라이브 사이트)과 클레임 URL(Vercel 계정으로 전환)을 반환합니다.
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]
인수:
path- 배포할 디렉토리, 또는.tgz파일(기본값은 현재 디렉토리)
예시:
# 현재 디렉토리 배포
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
# 특정 프로젝트 배포
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project
# 기존 tarball 배포
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz
스크립트는 package.json에서 프레임워크를 자동 감지하고, 프로젝트를 패키징하며(node_modules, .git, .env 제외), 업로드하고 빌드가 완료될 때까지 기다립니다.
사용자에게 알립니다: "배포가 준비되었습니다: [프리뷰Url]. [클레임Url]에서 클레임하여 배포를 관리하세요."
인증 없는 대체 방법 — Codex 샌드박스
사용 시기: CLI가 인증되지 않을 수 있는 Codex 샌드박스에서 사용합니다. Codex는 기본적으로 샌드박스 환경에서 실행됩니다. 먼저 CLI를 시도하고, 인증이 실패하면 배포 스크립트로 대체합니다.
-
Vercel CLI가 설치되어 있는지 확인합니다(이 확인에는 에스컬레이션이 필요하지 않음).
command -v vercel -
vercel이 설치된 경우, CLI로 배포를 시도합니다.vercel deploy [path] -y --no-wait -
vercel이 설치되지 않았거나 CLI가 "기존 자격 증명을 찾을 수 없음" 오류로 실패한 경우, 대체 스크립트를 사용합니다.skill_dir="<스킬-경로>" # 현재 디렉토리 배포 bash "$skill_dir/resources/deploy-codex.sh" # 특정 프로젝트 배포 bash "$skill_dir/resources/deploy-codex.sh" /path/to/project # 기존 tarball 배포 bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz
스크립트는 프레임워크 감지, 패키징 및 배포를 처리합니다. 빌드가 완료될 때까지 기다리고 previewUrl 및 claimUrl이 포함된 JSON을 반환합니다.
사용자에게 알립니다: "배포가 준비되었습니다: [프리뷰Url]. [클레임Url]에서 클레임하여 배포를 관리하세요."
에스컬레이티드 네트워크 액세스: 샌드박스가 네트워크 호출을 차단하는 경우에만 실제 배포 명령어를 에스컬레이션합니다(sandbox_permissions=require_escalated). command -v vercel 확인은 에스컬레이션하지 마십시오.
에이전트별 참고 사항
Claude Code / 터미널 기반 에이전트
완전한 셸 액세스 권한이 있습니다. /mnt/skills/ 경로를 사용하지 마십시오. 위의 결정 흐름을 따라 CLI를 직접 사용하십시오.
인증 없는 대체 방법의 경우, 스킬이 설치된 위치에서 배포 스크립트를 실행합니다.
bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]
경로는 사용자가 스킬을 설치한 위치에 따라 다를 수 있습니다.
샌드박스 환경 (claude.ai)
vercel login 또는 git push를 실행할 수 없을 가능성이 높습니다. 인증 없는 대체 방법 — claude.ai 샌드박스로 바로 이동합니다.
Codex
Codex는 샌드박스에서 실행됩니다. 먼저 CLI를 사용할 수 있는지 확인한 다음, 배포 스크립트로 대체합니다. 인증 없는 대체 방법 — Codex 샌드박스로 이동합니다.
출력
항상 사용자에게 배포 URL을 표시합니다.
- Git Push:
vercel ls --format json을 사용하여 프리뷰 URL을 찾습니다. CLI가 인증되지 않은 경우, 사용자에게 Vercel 대시보드 또는 커밋 상태 확인을 확인하라고 알립니다. - CLI 배포:
vercel deploy --no-wait가 반환한 URL을 표시합니다.vercel inspect <url>을 사용하여 빌드 상태를 확인하고 사용자에게 보고합니다. - 인증 없는 대체 방법: 프리뷰 URL과 클레임 URL을 모두 표시합니다.
배포 성공! 프리뷰 URL: https://my-app-abc123.vercel.app 클레임 URL: https://vercel.com/claim-deployment?code=... 프리뷰 URL에서 사이트를 확인하세요. 이 배포를 Vercel 계정으로 전환하려면 클레임 URL을 방문하세요.
배포된 URL을 curl하거나 fetch하여 작동하는지 확인하지 마십시오. 링크만 반환하십시오.
문제 해결
네트워크 이그레스 오류 (claude.ai)
claude.ai의 네트워크 제한으로 배포가 실패한 경우, 사용자에게 다음과 같이 알립니다.
네트워크 제한으로 배포에 실패했습니다. 해결 방법:
1. https://claude.ai/settings/capabilities로 이동합니다.
2. 허용된 도메인에 *.vercel.com을 추가합니다.
3. 다시 배포를 시도합니다.
에스컬레이티드 네트워크 액세스 (Codex / 샌드박스 환경)
샌드박스 환경에서 네트워크 문제(시간 초과, DNS 오류, 연결 재설정)로 배포가 실패한 경우, 에스컬레이션된 권한으로 다시 실행합니다(sandbox_permissions=require_escalated). 초기 CLI 가용성 확인은 에스컬레이션하지 말고, 실제 배포 명령어만 에스컬레이션합니다.
사용자에게 안내하는 예시:
Vercel에 배포하려면 에스컬레이션된 네트워크 액세스가 필요합니다.
에스컬레이션된 권한으로 명령어를 다시 실행할 수 있습니다 — 진행할까요?
CLI 인증 실패
vercel login 또는 vercel deploy가 인증 오류로 실패한 경우, 환경에 따라 인증 없는 배포 스크립트(claude.ai 또는 Codex 변형)로 대체합니다.