sam-react-prod/claudedocs/guides/[GUIDE-2025-12-29] vercel-deployment.md

Vercel 배포 가이드

작성일: 2025-12-29 상태: 🔄 진행 중 담당:

---

📋 배포 전 체크리스트

프로젝트 상태

• 빌드 테스트 성공
• Node.js v20.x 호환 확인
• Next.js 15 + next-intl 설정 완료
• 다국어 지원 (ko/en/ja)

배포 준비

• Vercel 계정 준비
• Git 레포지토리 연동
• 환경 변수 설정
• CORS 설정 요청 (백엔드)
• 배포 완료
• 테스트 완료

---

1단계: Vercel 프로젝트 생성

1.1 Vercel 접속

1. vercel.com 접속
2. GitHub/GitLab 계정으로 로그인

1.2 프로젝트 생성

1. Dashboard → Add New → Project
2. Git 레포지토리 선택: sam-react-prod
3. Framework Preset: Next.js (자동 감지)
4. Root Directory: . (기본값)

---

2단계: 환경 변수 설정

필수 환경 변수

변수명	값	환경	설명
NEXT_PUBLIC_API_URL	https://api.5130.co.kr	All	백엔드 API URL
NEXT_PUBLIC_FRONTEND_URL	(배포 후 URL)	Production	프론트엔드 URL
NEXT_PUBLIC_AUTH_MODE	sanctum	All	인증 모드
API_KEY	(실제 키)	All	서버사이드 API 키

설정 방법

1. Vercel Dashboard → Settings → Environment Variables
2. 각 변수 추가
3. Environment: Production / Preview / Development 선택

환경 변수 값 메모

NEXT_PUBLIC_API_URL =
NEXT_PUBLIC_FRONTEND_URL =
NEXT_PUBLIC_AUTH_MODE =
API_KEY =

---

3단계: 백엔드 CORS 설정

요청 내용

Vercel 배포 후 도메인을 백엔드팀에 전달하여 CORS 허용 요청

허용 요청 도메인:
- https://프로젝트명.vercel.app
- https://커스텀도메인.com (있는 경우)

백엔드 요청 메모

요청일:
요청 도메인:
처리 상태: [ ] 대기 / [ ] 완료

---

4단계: 배포 실행

4.1 첫 배포

1. 환경 변수 설정 완료 확인
2. Deploy 버튼 클릭
3. 빌드 로그 모니터링

4.2 배포 성공 확인

• 빌드 성공
• 배포 URL 생성
• 페이지 로딩 확인

배포 정보

배포 URL:
배포 시간:
빌드 시간:

---

5단계: 배포 후 테스트

5.1 기본 테스트

• 메인 페이지 로딩
• 로그인 페이지 접근
• 다국어 전환 (ko/en/ja)

5.2 인증 테스트

• 로그인 시도
• 토큰 발급 확인
• 로그아웃

5.3 API 연동 테스트

• API 호출 정상
• CORS 에러 없음
• 데이터 로딩 확인

5.4 주요 페이지 테스트

• 대시보드
• 품목기준관리
• 설정 페이지

테스트 결과 메모

테스트일:
발견된 이슈:
-

해결 필요 사항:
-

---

6단계: 커스텀 도메인 (선택)

6.1 도메인 연결

1. Vercel Dashboard → Settings → Domains
2. 도메인 추가: your-domain.com
3. DNS 설정 안내 확인

6.2 DNS 설정

Type: CNAME
Name: @ 또는 www
Value: cname.vercel-dns.com

도메인 정보

도메인:
SSL 상태: [ ] 대기 / [ ] 활성화

---

트러블슈팅

빌드 실패 시

# 로컬에서 빌드 테스트
npm run build

CORS 에러 시

• 백엔드 CORS 설정 확인
• NEXT_PUBLIC_FRONTEND_URL 값 확인

환경 변수 미적용 시

• Vercel Dashboard에서 값 확인
• 재배포 필요 (환경 변수 변경 후)

API 연결 실패 시

• NEXT_PUBLIC_API_URL 확인
• API_KEY 값 확인
• 네트워크 탭에서 요청/응답 확인

---

참고 자료

• Vercel Next.js 배포 가이드
• Next.js 환경 변수
• Vercel 커스텀 도메인

---

작업 로그

2025-12-29

• 가이드 문서 생성
• 배포 시작

추가 메모

(여기에 진행하면서 메모 추가)