Vercel 토큰 CLI

토큰을 사용한 Vercel CLI

vercel login 없이, CLI와 토큰 기반 인증을 사용하여 Vercel에서 프로젝트를 배포하고 관리합니다.

1단계: Vercel 토큰 찾기

Vercel CLI 명령을 실행하기 전에 토큰이 어디에서 오는지 확인합니다. 다음 시나리오를 순서대로 진행합니다:

A) 환경에 VERCEL_TOKEN이 이미 설정되어 있음

printenv VERCEL_TOKEN

값이 반환되면 준비가 된 것입니다. 2단계로 건너뜁니다.

B) .env 파일에 VERCEL_TOKEN으로 토큰이 있음

grep '^VERCEL_TOKEN=' .env 2>/dev/null

찾으면 내보냅니다:

export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)

C) .env 파일에 다른 이름으로 토큰이 있음

Vercel 토큰처럼 보이는 변수(Vercel 토큰은 일반적으로 vca_로 시작)를 찾습니다:

grep -i 'vercel' .env 2>/dev/null

출력 결과에서 토큰을 보유한 변수를 확인한 후 VERCEL_TOKEN으로 내보냅니다:

export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)

D) 토큰을 찾을 수 없음 — 사용자에게 문의

위의 어떤 방법으로도 토큰을 얻을 수 없으면 사용자에게 제공해 달라고 요청합니다. 사용자는 vercel.com/account/tokens에서 Vercel 액세스 토큰을 만들 수 있습니다.

---

중요: VERCEL_TOKEN이 환경 변수로 내보내지면 Vercel CLI가 기본적으로 읽습니다. --token 플래그로 전달하지 마십시오. 명령줄 인수에 시크릿을 넣으면 셸 기록과 프로세스 목록에 노출됩니다.

# 나쁜 예 — 토큰이 셸 기록과 프로세스 목록에 노출됨
vercel deploy --token "vca_abc123"

# 좋은 예 — CLI가 환경에서 VERCEL_TOKEN을 읽음
export VERCEL_TOKEN="vca_abc123"
vercel deploy

2단계: 프로젝트와 팀 찾기

마찬가지로 프로젝트 ID와 팀 스코프를 확인합니다. 이를 통해 CLI가 vercel link 없이도 올바른 프로젝트를 대상으로 할 수 있습니다.

# 환경 확인
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

# 또는 .env 확인
grep -i 'vercel' .env 2>/dev/null

프로젝트 URL이 있는 경우 (예: https://vercel.com/my-team/my-project), 팀 슬러그를 추출합니다:

# 예: "https://vercel.com/my-team/my-project"에서 "my-team" 추출
echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1

환경에 VERCEL_ORG_ID와 VERCEL_PROJECT_ID가 모두 있으면 내보냅니다. CLI가 자동으로 이를 사용하고 .vercel/ 디렉토리를 건너뜁니다:

export VERCEL_ORG_ID="<org-id>"
export VERCEL_PROJECT_ID="<project-id>"

참고: VERCEL_ORG_ID와 VERCEL_PROJECT_ID는 함께 설정해야 합니다. 하나만 설정하면 오류가 발생합니다.

CLI 설정

Vercel CLI가 설치되어 있고 최신 버전인지 확인합니다:

npm install -g vercel
vercel --version

프로젝트 배포

사용자가 명시적으로 요청하지 않는 한 항상 미리보기로 배포합니다. 사용 가능한 항목에 따라 방법을 선택합니다.

빠른 배포 (프로젝트 ID 있음 — 링크 불필요)

환경에 VERCEL_TOKEN과 VERCEL_PROJECT_ID가 설정되어 있으면 직접 배포합니다:

vercel deploy -y --no-wait

팀 스코프가 있는 경우 (VERCEL_ORG_ID 또는 --scope 사용):

vercel deploy --scope <team-slug> -y --no-wait

프로덕션 배포 (명시적으로 요청된 경우에만):

vercel deploy --prod --scope <team-slug> -y --no-wait

상태 확인:

vercel inspect <deployment-url>

전체 배포 흐름 (프로젝트 ID 없음 — 링크 필요)

토큰과 팀은 있지만 프로젝트 ID가 없는 경우에 사용합니다.

먼저 프로젝트 상태 확인

# 프로젝트에 git 원격이 있습니까?
git remote get-url origin 2>/dev/null

# 이미 Vercel 프로젝트에 연결되어 있습니까?
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

프로젝트 연결

git 원격이 있는 경우 (권장):

vercel link --repo --scope <team-slug> -y

git 원격을 읽고 일치하는 Vercel 프로젝트에 연결합니다. .vercel/repo.json을 생성합니다. 디렉토리 이름으로 일치시키는 일반 vercel link보다 더 안정적입니다.

git 원격이 없는 경우:

vercel link --scope <team-slug> -y

.vercel/project.json을 생성합니다.

특정 프로젝트 이름으로 연결:

vercel link --project <project-name> --scope <team-slug> -y

프로젝트가 이미 연결되어 있으면 .vercel/project.json 또는 .vercel/repo.json에서 orgId를 확인하여 의도한 팀과 일치하는지 확인합니다.

연결 후 배포

A) Git Push 배포 — git 원격 있음 (권장)

git 푸시는 자동으로 Vercel 배포를 트리거합니다.

1. 푸시하기 전에 사용자에게 물어보십시오. 명시적 승인 없이 푸시하지 마십시오.
2. 커밋 및 푸시:

   git add .
   git commit -m "deploy: <변경 사항 설명>"
   git push
   

3. Vercel이 자동으로 빌드합니다. 비프로덕션 브랜치는 미리보기 배포를 받습니다.
4. 배포 URL 검색:

   sleep 5
   vercel ls --format json --scope <team-slug>
   

   deployments 배열에서 최신 항목을 찾습니다.

B) CLI 배포 — git 원격 없음

vercel deploy --scope <team-slug> -y --no-wait

상태 확인:

vercel inspect <deployment-url>

원격 저장소에서 배포 (코드가 로컬에 클론되지 않음)

1. 저장소 클론:

   git clone <repo-url>
   cd <repo-name>
   

2. Vercel에 연결:

   vercel link --repo --scope <team-slug> -y
   

3. git push를 통해 배포 (푸시 액세스 권한이 있는 경우) 또는 CLI 배포.

.vercel/ 디렉토리 정보

연결된 프로젝트에는 다음 중 하나가 있습니다:

• .vercel/project.json — vercel link로 생성. projectId와 orgId를 포함합니다.
• .vercel/repo.json — vercel link --repo로 생성. orgId, remoteName 및 projects 맵을 포함합니다.

환경에 VERCEL_ORG_ID + VERCEL_PROJECT_ID가 모두 설정된 경우에는 필요하지 않습니다.

연결되지 않은 디렉토리에서 상태를 감지하기 위해 vercel project inspect 또는 vercel link를 실행하지 마십시오. 대화형으로 프롬프트가 표시되거나 부작용으로 자동 연결될 수 있습니다. vercel ls는 안전합니다 (연결되지 않은 디렉토리에서는 기본적으로 해당 스코프의 모든 배포를 표시합니다). vercel whoami는 어디서나 안전합니다.

환경 변수 관리

# 모든 환경에 설정
echo "value" | vercel env add VAR_NAME --scope <team-slug>

# 특정 환경에 설정 (production, preview, development)
echo "value" | vercel env add VAR_NAME production --scope <team-slug>

# 환경 변수 목록 보기
vercel env ls --scope <team-slug>

# 로컬 .env.local 파일로 환경 변수 가져오기
vercel env pull --scope <team-slug>

# 변수 제거
vercel env rm VAR_NAME --scope <team-slug> -y

배포 검사

# 최근 배포 목록
vercel ls --format json --scope <team-slug>

# 특정 배포 검사
vercel inspect <deployment-url>

# 빌드 로그 보기 (Vercel CLI v35+ 필요)
vercel inspect <deployment-url> --logs

# 런타임 요청 로그 보기 (기본적으로 실시간 추적; 일회성 스냅샷을 위해 --no-follow 추가)
vercel logs <deployment-url>

도메인 관리

# 도메인 목록
vercel domains ls --scope <team-slug>

# 프로젝트에 도메인 추가 — 연결되었거나 환경 변수로 연결된 디렉토리 (인수 1개)
vercel domains add <domain> --scope <team-slug>

# 도메인 추가 — 연결되지 않은 디렉토리 (<project> 위치 인수 필요)
vercel domains add <domain> <project> --scope <team-slug>

Stripe Projects 요금제 변경

이 프로젝트가 Stripe Projects로 관리되는 경우. 유료 또는 파괴적인 요금제 변경을 실행하기 전에 사용자에게 물어보십시오. 업그레이드는 실제 카드로 청구되고, 다운그레이드는 시트를 제거합니다.

먼저 stripe projects status --json을 실행하여 Vercel 리소스의 로컬 이름을 확인합니다. 아래 예제는 기본값(vercel-plan)을 가정합니다. stripe projects add 시간에 이름이 변경된 경우 실제 이름으로 대체하십시오.

• Pro로 업그레이드: stripe projects add vercel/pro (또는 stripe projects upgrade vercel-plan pro)
• Hobby로 다운그레이드: stripe projects downgrade vercel-plan hobby

Pro가 제공하는 기능

• 월 $20 플랫폼 요금, 월 $20 사용 크레딧 포함.
• 새 프로젝트에 대해 기본적으로 Turbo 빌드 머신 (30 vCPU, 60GB 메모리) — Hobby보다 훨씬 빠른 빌드.
• 1개의 배포 시트 + 무제한 무료 Viewer 시트 (읽기 전용 협업자, 미리보기 댓글).
• 더 높은 포함 할당량 (매월 1TB 빠른 데이터 전송, 1,000만 Edge 요청).
• 유료 추가 기능 사용 가능: SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.

전체 세부 정보: https://vercel.com/docs/plans/pro-plan

작업 규칙

• VERCEL_TOKEN을 --token 플래그로 절대 전달하지 마십시오. 환경 변수로 내보내고 CLI가 기본적으로 읽도록 하십시오.
• 사용자에게 묻기 전에 환경에서 토큰을 확인하십시오. 먼저 현재 환경과 .env 파일을 확인하십시오.
• 기본적으로 미리보기 배포를 사용하십시오. 명시적으로 요청된 경우에만 프로덕션에 배포하십시오.
• git에 푸시하기 전에 물어보십시오. 사용자의 승인 없이 커밋을 푸시하지 마십시오.
• .vercel/ 파일을 직접 수정하지 마십시오. CLI가 이 디렉토리를 관리합니다. 읽는 것(예: orgId 확인)은 괜찮습니다.
• 배포된 URL을 curl/fetch하여 확인하지 마십시오. 사용자에게 링크를 반환하기만 하면 됩니다.
• --format json을 사용하십시오. 구조화된 출력이 후속 단계에 도움이 될 때 사용합니다.
• -y를 사용하십시오. 확인을 요청하는 명령에서 대화형 차단을 방지하기 위해 사용합니다.

문제 해결

토큰을 찾을 수 없음

환경과 있는 .env 파일을 확인합니다:

printenv | grep -i vercel
grep -i vercel .env 2>/dev/null

인증 오류

CLI가 Authentication required 오류로 실패하는 경우:

• 토큰이 만료되었거나 유효하지 않을 수 있습니다.
• 확인: vercel whoami (환경에서 VERCEL_TOKEN 사용).
• 사용자에게 새 토큰을 요청하십시오.

잘못된 팀

스코프가 올바른지 확인합니다:

vercel whoami --scope <team-slug>

빌드 실패

빌드 로그를 확인합니다:

vercel inspect <deployment-url> --logs

일반적인 원인:

• 종속성 누락 — package.json이 완전하고 커밋되었는지 확인합니다.
• 환경 변수 누락 — vercel env add로 추가합니다.
• 프레임워크 잘못된 구성 — vercel.json을 확인합니다. Vercel은 package.json에서 프레임워크(Next.js, Remix, Vite 등)를 자동 감지합니다. 감지가 잘못된 경우 vercel.json으로 재정의합니다.

CLI가 설치되지 않음

npm install -g vercel