목표#
- Vercel CLI를 설치하고 로그인합니다.
- 로컬 폴더를 Vercel 프로젝트에 연결하고, 터미널에서 Preview·Production 배포를 실행합니다.
- 환경 변수, 배포 목록, 로그, 롤백을 터미널에서 관리합니다.
이 장은 선택 사항입니다. GitHub 연동만으로 자동 배포가 되므로 CLI 없이도 서비스 운영에는 문제가 없습니다. 환경 변수를 로컬로 내려받거나(vercel env pull), GitHub 없이 빠르게 배포해 보고 싶을 때 유용합니다.
사전 조건#
1. 설치#
npm i -g vercel설치 확인:
vercel --version전역 설치 없이 매번 최신 버전을 쓰려면 npx vercel <명령> 형태로 실행해도 됩니다.
Windows PowerShell에서 vercel.ps1 파일을 로드할 수 없습니다... 스크립트를 실행할 수 없으므로 오류가 나면 실행 정책 때문입니다. 현재 사용자에게만 적용되도록 아래 명령을 한 번 실행합니다.
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned2. 로그인#
vercel login안내에 따라 브라우저에서 로그인(GitHub 계정 사용)하고 승인하면 터미널에 로그인 완료 메시지가 나옵니다.
로그인한 계정 확인:
vercel whoami3. 로컬 폴더를 프로젝트에 연결하기#
프로젝트 폴더로 이동한 뒤 실행합니다.
cd my-app
vercel link- 연결할 팀(scope) 을 선택합니다.
- 기존 프로젝트에 연결할지 묻는 질문에
Yes를 선택합니다. - 프로젝트 이름(
my-app)을 선택하거나 입력합니다.
연결이 끝나면 폴더에 .vercel/ 폴더가 생깁니다. 이 폴더에는 프로젝트 ID 등 연결 정보가 들어 있습니다.
.vercel/ 폴더는 커밋하지 마세요. 1장의 .gitignore 예시에 이미 포함되어 있습니다.
4. 터미널에서 배포하기#
| 명령 | 하는 일 |
|---|---|
vercel | 현재 폴더를 Preview로 배포 |
vercel --prod | 현재 폴더를 Production으로 배포 |
# 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 pull | Development 환경 변수를 .env.local 파일로 내려받기 |
# 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> | 해당 배포를 다시 빌드·배포 |
# 도움말 보기
vercel --help
vercel env --help7. 로컬 개발 서버 (선택)#
vercel devVercel 환경과 비슷하게(환경 변수, 서버 함수 포함) 로컬에서 실행합니다.
Next.js, Vite 등은 프레임워크 자체 개발 서버(npm run dev)를 쓰는 것이 더 빠르고 안정적입니다. vercel env pull로 .env.local을 받은 뒤 npm run dev를 실행하는 방식을 권장합니다.
8. 자주 쓰는 명령 요약#
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 found | vercel login 다시 실행 |
다음 단계#
➡️ 9장. 문제 해결: 빌드·배포 과정에서 자주 겪는 오류와 해결법을 정리합니다.