refactor: simplify environment variable management

.env

@@ -1,11 +1,20 @@
 # env
 NEXT_PUBLIC_CURRENT_TERM=2025-2
 
+# Shared configuration across all environments
+# Environment-specific values should be set in Vercel dashboard or .env.production
+
 # Login mode configuration
 # true: HTTP-only 쿠키 + Zustand (보안 강화)
 # false: 로컬스토리지 + Zustand (개발/테스트 편의)
 NEXT_PUBLIC_COOKIE_LOGIN_ENABLED=true
 
+# Stage API (default for PR/Preview and main branch)
+# Production API is configured via Vercel CLI in release workflow
+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
+
 NEXT_PUBLIC_IMAGE_URL=https://d1q5o8tzvz4j3d.cloudfront.net
 NEXT_PUBLIC_UPLOADED_IMAGE_URL=https://d23lwokhcc3r0c.cloudfront.net
 

.env.guide.md

@@ -0,0 +1,53 @@
+# Environment Variables Setup Guide
+
+## Structure
+
+### `.env`
+- **용도**: 모든 환경의 기본값 (stage API)
+- **커밋**: ✅ Git에 포함
+- **사용**: PR, Preview, main 브랜치 배포
+
+### `.env.production`
+- **용도**: Production API (릴리즈 전용)
+- **커밋**: ✅ Git에 포함
+- **사용**: 수동 릴리즈 워크플로우에서만 사용
+
+### `.env.local` (권장)
+- **용도**: 로컬 개발 환경별 설정
+- **커밋**: ❌ Git에서 제외 (.gitignore)
+- **사용**: 개발자별 로컬 설정 (포트, 로컬 API 등)
+
+## Deployment Flow
+
+### 1. PR/Preview (자동)
+- Vercel Integration 사용
+- `.env` 기본값 사용 (stage API)
+
+### 2. Main 브랜치 머지 (자동)
+- Vercel Integration 사용
+- `.env` 기본값 사용 (stage API)
+
+### 3. 릴리즈 (수동)
+- GitHub Actions의 release.yml 워크플로우
+- `--build-env` 플래그로 production API 주입
+- `.env.production`의 값들을 명시적으로 주입
+
+## Best Practices
+
+1. **민감 정보는 환경 변수에 넣지 않기**
+   - `NEXT_PUBLIC_*` 접두사는 클라이언트에 노출됨
+   - API 키 등은 서버 사이드에서만 사용
+
+2. **로컬 개발 시 `.env.local` 사용**
+   ```bash
+   # .env.local (gitignore됨)
+   NEXT_PUBLIC_WEB_URL=http://localhost:3000
+   NEXT_PUBLIC_API_SERVER_URL=http://localhost:8080
+   ```
+
+3. **환경별 우선순위 이해**
+   - Vercel CLI `--build-env` > `.env.production` > `.env.local` > `.env`
+
+4. **Vercel 대시보드 환경 변수는 사용하지 않음**
+   - 파일 기반 관리로 투명성 확보
+   - release.yml의 `--build-env`로 production 값 명시적 주입

.github/workflows/build.yml

@@ -0,0 +1,67 @@
+name: Build and Vercel Production Deployment on Main
+permissions:
+  contents: write
+
+env:
+  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+  VERCEL_ENV: production
+
+on:
+  push:
+    branches:
+      - main
+
+  workflow_dispatch:
+
+jobs:
+  generate_tag:
+    uses: ./.github/workflows/headver-tagging.yml
+    with: {}
+
+  Deploy-Production:
+    runs-on: ubuntu-latest
+    needs: generate_tag
+    env:
+      VERSION_TAG: ${{ needs.generate_tag.outputs.version }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 9
+
+      - name: Install Vercel CLI
+        run: pnpm add --global vercel@latest
+
+      - name: Clean Vercel Directory
+        run: rm -rf .vercel
+
+      - name: Pull Vercel Environment Information
+        run: |
+          vercel pull \
+            --yes \
+            --environment=${{ env.VERCEL_ENV }} \
+            --token=${{ secrets.VERCEL_TOKEN }}
+
+      - name: Build Project Artifacts
+        run: |
+          vercel build \
+            --yes \
+            --target=${{ env.VERCEL_ENV }} \
+
+            --token=${{ secrets.VERCEL_TOKEN }}
+
+      - name: Deploy Project Artifacts to Vercel
+        run: |
+          vercel deploy \
+            --prebuilt \
+            --target=${{ env.VERCEL_ENV }} \
+
+            --token=${{ secrets.VERCEL_TOKEN }}
+
+      - name: Output Tag Version
+        run: echo "Deployment completed for version $VERSION_TAG"
+
+

.github/workflows/release.yml

@@ -57,7 +57,14 @@ jobs:
         run: vercel pull --yes --environment=${{ env.VERCEL_ENV }} --token=${{ secrets.VERCEL_TOKEN }}
 
       - name: Build Project Artifacts
-        run: vercel build --yes --target=${{ env.VERCEL_ENV }} --token=${{ secrets.VERCEL_TOKEN }}
+        run: |
+          vercel build \
+            --yes \
+            --target=${{ env.VERCEL_ENV }} \
+            --build-env NEXT_PUBLIC_WEB_URL=https://www.solid-connection.com \
+            --build-env NEXT_PUBLIC_API_SERVER_URL=https://api.solid-connection.com \
+            --build-env NEXT_PUBLIC_KAKAO_JS_KEY=b285223d3e57a6820552018b93805658 \
+            --token=${{ secrets.VERCEL_TOKEN }}
 
       - name: Deploy Project Artifacts to Vercel
         run: vercel deploy --prebuilt --target=${{ env.VERCEL_ENV }} --token=${{ secrets.VERCEL_TOKEN }}