Skip to content

.env.guide.md

Latest commit

 

History

History
120 lines (88 loc) · 3.83 KB

.env.guide.md

File metadata and controls

120 lines (88 loc) · 3.83 KB

Environment Variables Setup Guide

Monorepo Structure

이 프로젝트는 모노레포 구조로 web과 admin 앱을 포함합니다:

  • apps/web: Next.js 기반 웹 애플리케이션 (NEXT_PUBLIC_* 환경 변수)
  • apps/admin: Vite 기반 어드민 애플리케이션 (VITE_* 환경 변수)

각 앱은 독립적인 환경 변수를 가지며, 공통 빌드 도구 설정은 packages/config에서 관리됩니다.

Architecture Decision

Why Only .env.development and .env.production?

문제점: Next.js는 production 빌드 시 .env.preview를 인식하지 않습니다. Vercel Integration의 preview 배포도 NODE_ENV=production으로 빌드되기 때문에 .env.production을 로드합니다.

해결 방안:

  1. ❌ .env.preview 파일 사용 → Next.js가 인식하지 못함
  2. ✅ Vercel 대시보드에서 환경 변수 관리 (채택)
    • Preview 환경: stage API 설정
    • Production 환경: production API 설정 (또는 파일 사용)

장점:

  • 환경별로 명확한 값 관리 가능
  • 파일 기반 .env는 로컬 개발용으로만 사용
  • Vercel의 환경 변수가 파일보다 우선순위가 높아 배포 시 정확히 적용됨

File Structure

.env

  • 용도: 모든 환경의 공통 기본값
  • 커밋: ✅ Git에 포함
  • 내용: 공통 설정 (IMAGE_URL 등)

.env.development

  • 용도: 로컬 개발 환경 (npm run dev)
  • 커밋: ✅ Git에 포함
  • 내용: localhost:3000, stage API, 로컬스토리지 로그인

.env.production

  • 용도: Production 배포 참고용
  • 커밋: ✅ Git에 포함
  • 사용: release.yml의 --build-env 플래그로 값 주입 시 참고

.env.local (옵션)

  • 용도: 개발자별 로컬 설정
  • 커밋: ❌ Git에서 제외 (.gitignore)
  • 사용: 개인 테스트 키, 로컬 API 서버 등

Deployment Flow

1. 로컬 개발 (npm run dev)

  • NODE_ENV=development
  • .env.development 사용
  • localhost:3000, stage API

2. PR/Preview (Vercel Integration)

  • NODE_ENV=production (빌드)
  • Vercel Preview 환경 변수 사용 ⭐
  • stage 도메인, stage API
  • ⚠️ .env.preview는 Next.js가 인식하지 않으므로 사용 불가

3. Main 브랜치 머지 (Vercel Integration)

  • NODE_ENV=production (빌드)
  • Vercel Production 환경 변수 사용 ⭐
  • production 도메인, production API

4. 수동 릴리즈 (release.yml)

  • NODE_ENV=production (빌드)
  • --build-env 플래그로 production API 명시적 주입
  • GitHub Release 태그 생성

Vercel Dashboard Setup

Preview 환경 변수 설정

SENTRY_ENVIRONMENT=preview
NEXT_PUBLIC_WEB_URL=https://www.stage.solid-connection.com
NEXT_PUBLIC_API_SERVER_URL=https://api.stage.solid-connection.com
NEXT_PUBLIC_KAKAO_JS_KEY=c080f1d215a69b47401cda1d7528418a

Production 환경 변수 설정

SENTRY_ENVIRONMENT=production
NEXT_PUBLIC_WEB_URL=https://www.solid-connection.com
NEXT_PUBLIC_API_SERVER_URL=https://api.solid-connection.com
NEXT_PUBLIC_KAKAO_JS_KEY=b285223d3e57a6820552018b93805658

Best Practices

  1. 환경별 값은 Vercel 대시보드에서 관리

    • Preview/Production 환경에서 다른 API를 사용해야 할 때
    • 파일보다 Vercel 환경 변수가 우선순위가 높음

  2. 로컬 개발 시 .env.local 활용

    # .env.local (gitignore됨)
NEXT_PUBLIC_API_SERVER_URL=http://localhost:8080

  3. 환경별 우선순위

    • Vercel 환경 변수 > Vercel CLI --build-env > .env.production > .env.local > .env.development > .env

  4. .env.preview를 사용하지 않는 이유

    • Next.js는 production 빌드 시 .env.preview를 로드하지 않음
    • Vercel의 preview 배포도 NODE_ENV=production으로 빌드됨
    • 대신 Vercel 대시보드의 Preview 환경 변수 사용