배포 매뉴얼
전체 목차08 · Vercel CLI (선택)
Chapter 08

Vercel CLI (선택)

최종 확인일 2026-11-04 읽는 시간 약 6분 부록 · 도구와 문제 해결

목표#

  • Vercel CLI를 설치하고 로그인합니다.
  • 로컬 폴더를 Vercel 프로젝트에 연결하고, 터미널에서 Preview·Production 배포를 실행합니다.
  • 환경 변수, 배포 목록, 로그, 롤백을 터미널에서 관리합니다.
참고

이 장은 선택 사항입니다. GitHub 연동만으로 자동 배포가 되므로 CLI 없이도 서비스 운영에는 문제가 없습니다. 환경 변수를 로컬로 내려받거나(vercel env pull), GitHub 없이 빠르게 배포해 보고 싶을 때 유용합니다.

사전 조건#

  • Node.js와 npm이 설치되어 있습니다. (0장)
  • 3장에서 Vercel 프로젝트가 만들어져 있습니다.

1. 설치#

bash
npm i -g vercel

설치 확인:

bash
vercel --version
팁

전역 설치 없이 매번 최신 버전을 쓰려면 npx vercel <명령> 형태로 실행해도 됩니다.

주의

Windows PowerShell에서 vercel.ps1 파일을 로드할 수 없습니다... 스크립트를 실행할 수 없으므로 오류가 나면 실행 정책 때문입니다. 현재 사용자에게만 적용되도록 아래 명령을 한 번 실행합니다.

PowerShell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

2. 로그인#

bash
vercel login

안내에 따라 브라우저에서 로그인(GitHub 계정 사용)하고 승인하면 터미널에 로그인 완료 메시지가 나옵니다.

로그인한 계정 확인:

bash
vercel whoami

3. 로컬 폴더를 프로젝트에 연결하기#

프로젝트 폴더로 이동한 뒤 실행합니다.

bash
cd my-app
vercel link
  1. 연결할 팀(scope) 을 선택합니다.
  2. 기존 프로젝트에 연결할지 묻는 질문에 Yes를 선택합니다.
  3. 프로젝트 이름(my-app)을 선택하거나 입력합니다.

연결이 끝나면 폴더에 .vercel/ 폴더가 생깁니다. 이 폴더에는 프로젝트 ID 등 연결 정보가 들어 있습니다.

중요

.vercel/ 폴더는 커밋하지 마세요. 1장의 .gitignore 예시에 이미 포함되어 있습니다.


4. 터미널에서 배포하기#

명령하는 일
vercel현재 폴더를 Preview로 배포
vercel --prod현재 폴더를 Production으로 배포
bash
# Preview 배포
vercel

# Production 배포
vercel --prod

배포가 끝나면 터미널에 배포 URL이 출력됩니다.

주의

CLI 배포는 로컬 폴더의 현재 상태를 그대로 올립니다. 커밋하지 않은 변경 사항도 포함되며, GitHub main과 다른 내용이 Production에 올라갈 수 있습니다. 팀으로 일한다면 Production 배포는 6장처럼 PR 병합으로만 하는 것을 권장합니다.


5. 환경 변수 관리#

명령하는 일
vercel env ls등록된 환경 변수 목록 보기
vercel env add <이름> <환경>환경 변수 추가 (값은 입력 프롬프트에서 입력)
vercel env rm <이름> <환경>환경 변수 삭제
vercel env pullDevelopment 환경 변수를 .env.local 파일로 내려받기
bash
# Production 환경에 변수 추가 (값은 프롬프트에서 입력)
vercel env add WEATHER_API_KEY production

# 로컬 개발용 .env.local 생성
vercel env pull
팁

값을 명령어 인자로 직접 적지 말고 프롬프트에서 입력하세요. 명령어 기록(history)에 비밀 값이 남지 않습니다.

참고

vercel env pull은 기본적으로 Development 환경의 값을 내려받습니다. Sensitive로 지정한 변수는 값이 내려오지 않을 수 있습니다. (5장)


6. 배포 확인·로그·롤백#

명령하는 일
vercel ls최근 배포 목록
vercel inspect <배포 URL>특정 배포의 상세 정보
vercel inspect <배포 URL> --logs해당 배포의 빌드 로그 보기
vercel logs <배포 URL>실행 중 로그(서버 함수) 보기
vercel promote <배포 URL>해당 배포를 Production으로 승격
vercel rollback이전 Production 배포로 롤백
vercel redeploy <배포 URL>해당 배포를 다시 빌드·배포
bash
# 도움말 보기
vercel --help
vercel env --help

7. 로컬 개발 서버 (선택)#

bash
vercel dev

Vercel 환경과 비슷하게(환경 변수, 서버 함수 포함) 로컬에서 실행합니다.

팁

Next.js, Vite 등은 프레임워크 자체 개발 서버(npm run dev)를 쓰는 것이 더 빠르고 안정적입니다. vercel env pull로 .env.local을 받은 뒤 npm run dev를 실행하는 방식을 권장합니다.


8. 자주 쓰는 명령 요약#

bash
npm i -g vercel        # 설치
vercel login           # 로그인
vercel link            # 로컬 폴더 ↔ Vercel 프로젝트 연결
vercel                 # Preview 배포
vercel --prod          # Production 배포
vercel env pull        # 환경 변수를 .env.local로 내려받기
vercel ls              # 배포 목록
vercel rollback        # 이전 Production으로 롤백

확인 방법#

문제 해결#

증상원인과 해결
vercel : 이 시스템에서 스크립트를 실행할 수 없으므로...PowerShell 실행 정책 → 1단계의 Set-ExecutionPolicy 실행
vercel : 용어가 cmdlet... 으로 인식되지 않습니다설치 후 터미널 재시작, 또는 npx vercel 사용
엉뚱한 프로젝트에 배포됨.vercel/ 폴더 삭제 후 vercel link 다시 실행
Error: No existing credentials foundvercel login 다시 실행

다음 단계#

➡️ 9장. 문제 해결: 빌드·배포 과정에서 자주 겪는 오류와 해결법을 정리합니다.

참고 자료#