Merge pull request #382 from solid-connection/fix/vercel-build

docs: update env setup to use Vercel dashboard for preview/production

Author: manNomi

.env.guide.md

@@ -1,62 +1,109 @@
 # 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
    # .env.local (gitignore됨)
    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 환경 변수 사용