diff --git a/.env.guide.md b/.env.guide.md index c85dcf05..2bc6cc03 100644 --- a/.env.guide.md +++ b/.env.guide.md @@ -1,55 +1,98 @@ # Environment Variables Setup Guide -## Structure +## 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에 포함 -- **내용**: 공통 값만 (CURRENT_TERM, IMAGE_URL, GOOGLE_MAPS_KEY 등) +- **내용**: 공통 설정 (CURRENT_TERM, IMAGE_URL 등) ### `.env.development` - **용도**: 로컬 개발 환경 (`npm run dev`) - **커밋**: ✅ Git에 포함 - **내용**: localhost:3000, stage API, 로컬스토리지 로그인 -### `.env.preview` -- **용도**: Vercel Preview 배포 (PR) -- **커밋**: ✅ Git에 포함 -- **내용**: stage 도메인, stage API, 쿠키 로그인 - ### `.env.production` -- **용도**: Production 배포 +- **용도**: Production 배포 참고용 - **커밋**: ✅ Git에 포함 -- **내용**: production 도메인, production API, 쿠키 로그인 +- **사용**: release.yml의 `--build-env` 플래그로 값 주입 시 참고 -### `.env.local` (권장) +### `.env.local` (옵션) - **용도**: 개발자별 로컬 설정 - **커밋**: ❌ Git에서 제외 (.gitignore) -- **내용**: 로컬 API 서버, 개인 테스트 키 등 +- **사용**: 개인 테스트 키, 로컬 API 서버 등 + +--- ## Deployment Flow ### 1. 로컬 개발 (`npm run dev`) +- `NODE_ENV=development` - `.env.development` 사용 - localhost:3000, stage API ### 2. PR/Preview (Vercel Integration) -- `.env.preview` 사용 +- `NODE_ENV=production` (빌드) +- **Vercel Preview 환경 변수** 사용 ⭐ - stage 도메인, stage API +- ⚠️ `.env.preview`는 Next.js가 인식하지 않으므로 사용 불가 ### 3. Main 브랜치 머지 (Vercel Integration) -- `.env.production` 사용 +- `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. **환경별 파일 분리** - - 각 환경의 설정을 명확히 분리 - - 공통 설정은 `.env`에만 +1. **환경별 값은 Vercel 대시보드에서 관리** + - Preview/Production 환경에서 다른 API를 사용해야 할 때 + - 파일보다 Vercel 환경 변수가 우선순위가 높음 2. **로컬 개발 시 `.env.local` 활용** ```bash @@ -57,6 +100,10 @@ NEXT_PUBLIC_API_SERVER_URL=http://localhost:8080 ``` -3. **환경별 우선순위 이해** - - `.env.[mode].local` > `.env.[mode]` > `.env.local` > `.env` - - Vercel CLI `--build-env`는 모든 파일보다 우선 +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 환경 변수 사용