Vercel에 배포은(는) 무엇을 하나요?
모든 프로젝트를 Vercel에 배포합니다. 사용자가 명시적으로 프로덕션을 요청하지 않는 한 항상 프리뷰(preview)로 배포합니다.
목표는 사용자를 최적의 장기 설정, 즉 프로젝트를 Vercel에 연결하고 Git 푸시로 배포하는 상태로 이끄는 것입니다. 아래의 모든 방법은 사용자를 그 상태에 더 가깝게 만듭니다.
1단계: 프로젝트 상태 확인
어떤 방법을 사용할지 결정하기 전에 네 가지를 모두 실행하세요:
# 1. Git 리모트 확인
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 <team-slug>
프로젝트가 이미 연결된 경우(.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단계: 배포 방법 선택
연결됨 (.vercel/ 존재) + git 리모트 있음 → Git Push
이상적인 상태입니다. 프로젝트가 연결되어 있고 Git 통합이 설정되어 있습니다.
-
푸시하기 전에 사용자에게 물어보세요. 명시적인 승인 없이 절대 푸시하지 마세요:
이 프로젝트는 Git을 통해 Vercel에 연결되어 있습니다. 변경 사항을 커밋하고 푸시하여 배포를 트리거할 수 있습니다. 진행할까요? -
커밋하고 푸시하기:
git add . git commit -m "deploy: <변경 사항 설명>" git pushVercel이 푸시에서 자동으로 빌드합니다. 프로덕션 브랜치가 아닌 브랜치는 프리뷰 배포를 받고, 프로덕션 브랜치(보통
main)는 프로덕션 배포를 받습니다. -
프리뷰 URL 가져오기. CLI가 인증된 경우:
sleep 5 vercel ls --format jsonJSON 출력에는
deployments배열이 있습니다. 최신 항목의url필드가 프리뷰 URL입니다.CLI가 인증되지 않은 경우, 사용자에게 Vercel 대시보드 또는 Git 제공업체의 커밋 상태 확인에서 프리뷰 URL을 확인하라고 알려주세요.
연결됨 (.vercel/ 존재) + git 리모트 없음 → vercel deploy
프로젝트는 연결되어 있지만 Git 레포지토리가 없습니다. CLI로 직접 배포하세요.
vercel deploy [path] -y --no-wait
--no-wait를 사용하여 빌드가 완료될 때까지 기다리지 않고 CLI가 즉시 배포 URL을 반환하도록 합니다(빌드는 시간이 걸릴 수 있습니다). 그런 다음 다음 명령어로 배포 상태를 확인하세요:
vercel inspect <deployment-url>
프로덕션 배포의 경우(사용자가 명시적으로 요청한 경우에만):
vercel deploy [path] --prod -y --no-wait
연결 안 됨 + CLI 인증됨 → 먼저 연결한 후 배포
CLI는 작동하지만 프로젝트가 아직 연결되지 않았습니다. 이 기회에 사용자를 최상의 상태로 만들어 주세요.
-
사용자에게 어느 팀에 배포할지 물어보세요. 1단계의 팀 슬러그를 글머리 기호 목록으로 제시하세요. 팀이 하나뿐이거나(또는 개인 계정만 있는 경우) 이 단계를 건너뛰세요.
-
팀이 선택되면 바로 연결을 진행하세요. 무슨 일이 일어날지 사용자에게 알리되, 별도의 확인을 요청하지 마세요:
이 프로젝트를 Vercel의 <team name>에 연결합니다. 이렇게 하면 배포할 Vercel 프로젝트가 생성되고 향후 Git 푸시 시 자동 배포가 활성화됩니다. -
git 리모트가 존재하면, 선택한 팀 스코프로 레포지토리 기반 연결을 사용하세요:
vercel link --repo --scope <team-slug>이 명령어는 git 리모트 URL을 읽고 해당 레포지토리에서 배포하는 기존 Vercel 프로젝트와 일치시킵니다.
.vercel/repo.json을 생성합니다. 이것은 일반vercel link(--repo없이)보다 훨씬 안정적입니다. 일반vercel link는 디렉토리 이름으로 일치시키려고 시도하며 로컬 폴더와 Vercel 프로젝트 이름이 다를 때 자주 실패합니다.git 리모트가 없으면 표준 연결로 대체하세요:
vercel link --scope <team-slug>이 명령어는 사용자에게 프로젝트를 선택하거나 생성하도록 요청합니다.
.vercel/project.json을 생성합니다. -
그런 다음 사용 가능한 최상의 방법으로 배포하세요:
- git 리모트가 존재하면 → 커밋 및 푸시 (위의 git push 방법 참조)
- git 리모트가 없으면 →
vercel deploy [path] -y --no-wait --scope <team-slug>, 그 다음vercel inspect <url>로 상태 확인
연결 안 됨 + CLI 인증 안 됨 → 설치, 인증, 연결, 배포
Vercel CLI가 전혀 설정되지 않았습니다.
-
CLI 설치 (아직 설치되지 않은 경우):
npm install -g vercel -
인증:
vercel login사용자가 브라우저에서 인증을 완료합니다. 대화형 환경이 아닌 경우, 아래 인증 없는 대체로 건너뛰세요.
-
어느 팀에 배포할지 물어보세요:
vercel teams list --format json의 팀 슬러그를 글머리 기호 목록으로 제시하세요. 팀이 하나뿐이거나 개인 계정만 있는 경우 건너뛰세요. 선택되면 즉시 진행하세요. -
선택한 팀 스코프로 프로젝트 연결 (git 리모트가 있으면
--repo사용, 그렇지 않으면 일반vercel link):vercel link --repo --scope <team-slug> # git 리모트가 있는 경우 vercel link --scope <team-slug> # git 리모트가 없는 경우 -
사용 가능한 최상의 방법으로 배포 (리모트가 있으면 git push, 그렇지 않으면
vercel deploy -y --no-wait --scope <team-slug>, 그 다음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 제외), 업로드하고 빌드가 완료될 때까지 기다립니다.
사용자에게 알리기: "배포가 준비되었습니다: [previewUrl]. [claimUrl]에서 클레임하여 배포를 관리하세요."
인증 없는 대체. Codex 샌드박스
사용 시기: Codex 샌드박스에서 CLI가 인증되지 않을 수 있습니다. Codex는 기본적으로 샌드박스 환경에서 실행되므로, 먼저 CLI를 시도하고 인증이 실패하면 배포 스크립트로 대체하세요.
-
Vercel CLI가 설치되어 있는지 확인 (이 확인에는 권한 상승이 필요하지 않음):
command -v vercel -
vercel이 설치된 경우, CLI로 배포를 시도하세요:vercel deploy [path] -y --no-wait -
vercel이 설치되지 않았거나 CLI가 "No existing credentials found" 오류로 실패한 경우, 대체 스크립트를 사용하세요:skill_dir="<skill-경로>" # 현재 디렉토리 배포 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을 반환합니다.
사용자에게 알리기: "배포가 준비되었습니다: [previewUrl]. [claimUrl]에서 클레임하여 배포를 관리하세요."
권한 상승된 네트워크 액세스: 샌드박스가 네트워크 호출을 차단하는 경우에만 실제 배포 명령어의 권한을 상승시키세요(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 변형, 환경에 따라 다름).