Vercel CLI (토큰 기반)

Vercel CLI with Tokens (토큰 기반 Vercel CLI)

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

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 '^<변수_이름>=' .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와 팀 범위(scope)를 확인합니다. 이 값을 통해 vercel link 없이도 CLI가 올바른 프로젝트를 대상으로 할 수 있습니다.

# 환경 확인
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

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

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

# 예: "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

팀 범위(scope) 사용 시 (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 원격(remote)이 있습니까?
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 푸시 (푸시 액세스 권한이 있는 경우) 또는 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 "값" | vercel env add VAR_NAME --scope <team-slug>

# 특정 환경에 설정 (production, preview, development)
echo "값" | 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에서 관리되는 경우입니다. 유료 또는 파괴적인 요금제 변경을 실행하기 전에 사용자에게 문의하세요. 업그레이드는 실제 카드에 청구되고, 다운그레이드는 시트(seats)를 제거합니다.

먼저 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 vCPUs, 60 GB 메모리) — Hobby보다 훨씬 빠른 빌드.
• 1개의 배포 시트 + 무제한 무료 뷰어 시트 (읽기 전용 협업자, 프리뷰 댓글).
• 더 높은 포함 할당량 (월 1TB 빠른 데이터 전송, 1천만 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 사용).
• 사용자에게 새 토큰을 요청하세요.

잘못된 팀

범위(scope)가 올바른지 확인하세요:

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으로 재정의(override)하세요.

CLI가 설치되지 않음

npm install -g vercel