SamProject/sam-react-prod
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
develop
sam-react-prod/claudedocs/vercel/vercel-env-setup-guide.md
유병철 f320ec7d37 feat(WEB): Vercel 배포 대응 및 타입 안정성 개선 
- puppeteer → puppeteer-core + @sparticuz/chromium 전환 (Vercel 서버리스 호환)
- PDF 생성 API 로컬/Vercel 환경 분기 처리
- next.config.ts: ignoreBuildErrors false로 전환
- WorkOrder items에 orderNodeId/orderNodeName 필드 추가
- 결재선 데이터에 name/dept 필드 추가
- OrderSalesDetailView 타입 캐스팅 안전하게 수정
- vercel.json 설정 추가

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 10:45:57 +09:00

3.1 KiB
Raw Permalink Blame History

Vercel 환경변수 설정 가이드

설정 위치

Vercel Dashboard → Project → Settings → Environment Variables

필수 환경변수

서버 전용 (Server-side Only)

변수명 설명 예시 값 환경
API_KEY 백엔드 API 인증 키 (X-API-KEY 헤더) 42Jfwc6Ea... Production, Preview
API_URL 백엔드 API 내부 URL (서버 사이드 전용) https://api.codebridge-x.com Production, Preview

API_KEY는 절대 NEXT_PUBLIC_ 접두사를 붙이지 말 것. 클라이언트에 노출되면 안 됨.

클라이언트 공개 (NEXT_PUBLIC_*)

변수명 설명 Production 값 Preview 값
NEXT_PUBLIC_API_URL 프론트엔드에서 호출하는 API URL https://api.codebridge-x.com https://api.codebridge-x.com
NEXT_PUBLIC_FRONTEND_URL 프론트엔드 자체 URL (CORS 용) https://dev.codebridge-x.com Vercel 자동 할당 URL
NEXT_PUBLIC_AUTH_MODE 인증 모드 sanctum sanctum
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY Google Maps API 키 AIzaSy... AIzaSy...
NEXT_PUBLIC_DEV_TOOLBAR_ENABLED 개발 도구 툴바 false true

선택 환경변수

변수명 설명 기본값
NEXT_PUBLIC_API_LOGGING API 로깅 활성화 미설정 (비활성)
NEXT_PUBLIC_APP_VERSION 앱 버전 표시 미설정
PUPPETEER_EXECUTABLE_PATH Chromium 경로 (Vercel에서는 불필요) 미설정

환경별 설정 방법

1. Vercel Dashboard에서 설정

  1. Vercel Dashboard 접속
  2. 프로젝트 선택 → Settings → Environment Variables
  3. 각 변수 추가 시 적용 환경 선택:
    • Production: 운영 배포에만 적용
    • Preview: PR/브랜치 배포에 적용
    • Development: vercel dev 로컬 실행 시 적용

2. 환경별 권장 설정

Production

API_KEY=<실제 운영 API 키>
API_URL=https://api.codebridge-x.com
NEXT_PUBLIC_API_URL=https://api.codebridge-x.com
NEXT_PUBLIC_FRONTEND_URL=https://<운영 도메인>
NEXT_PUBLIC_AUTH_MODE=sanctum
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=<Google Maps 키>
NEXT_PUBLIC_DEV_TOOLBAR_ENABLED=false

Preview

API_KEY=<개발용 API 키>
API_URL=https://api.codebridge-x.com
NEXT_PUBLIC_API_URL=https://api.codebridge-x.com
NEXT_PUBLIC_FRONTEND_URL=<Vercel Preview URL - 자동>
NEXT_PUBLIC_AUTH_MODE=sanctum
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=<Google Maps 키>
NEXT_PUBLIC_DEV_TOOLBAR_ENABLED=true

주의사항

  1. API_KEY 보안: Sensitive 체크박스를 반드시 활성화하여 Dashboard에서도 값이 마스킹되도록 설정
  2. NEXT_PUBLIC_ 접두사: 이 접두사가 붙은 변수는 클라이언트 번들에 포함되므로 민감 정보 절대 금지
  3. VERCEL 환경변수: VERCEL=1은 Vercel이 자동 주입하므로 별도 설정 불필요 (PDF 생성 분기에 사용)
  4. NODE_ENV: Vercel이 자동 설정 (production for Production, development for Preview)