[fix] front: Vite 8 에서 금지된 local 모드 제거

- Vite 8 은 'local' 을 모드 이름으로 허용하지 않음(.env.local 접미사 충돌)
- dev 스크립트를 'vite --mode local' → 'vite' 로 변경 (.env.local 은 자동 로드)
- README 환경 변수/실행 안내를 실제 동작에 맞게 갱신

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
민헌 2026-06-16 13:17:35 +09:00
parent fbbe8b3427
commit f5721afa21
2 changed files with 10 additions and 10 deletions

View File

@ -38,23 +38,23 @@ npm run dev
Vite 의 mode 기능으로 환경별 env 파일을 매핑한다. 클라이언트 번들에 노출되는 변수는 반드시 `VITE_` 접두사를 붙인다. Vite 의 mode 기능으로 환경별 env 파일을 매핑한다. 클라이언트 번들에 노출되는 변수는 반드시 `VITE_` 접두사를 붙인다.
| 파일 | mode | 용도 | git | | 파일 | 사용 시점 | git |
| --- | --- | --- | --- | | --- | --- | --- |
| `.env.sample` | - | 템플릿 (키 목록 공유용) | ✅ 커밋 | | `.env.sample` | 템플릿 (키 목록 공유용) | ✅ 커밋 |
| `.env.local` | `local` | 로컬 개발 | 🚫 ignore | | `.env.local` | 로컬 개발 (`npm run dev`, Vite 가 자동 로드) | 🚫 ignore |
| `.env.dev` | `dev` | 개발 서버 | 🚫 ignore | | `.env.dev` | `--mode dev` (개발 서버) | 🚫 ignore |
| `.env.prod` | `prod` | 운영 | 🚫 ignore | | `.env.prod` | `--mode prod` (운영) | 🚫 ignore |
새 환경 세팅 시 `.env.sample` 을 복사해 환경별 파일을 만들고 값을 채운다. 코드에서는 `import.meta.env.VITE_API_BASE_URL` 처럼 접근한다. 새 환경 세팅 시 `.env.sample` 을 복사해 환경별 파일을 만들고 값을 채운다. 코드에서는 `import.meta.env.VITE_API_BASE_URL` 처럼 접근한다.
> 참고: Vite 는 mode 와 무관하게 `.env.local` 을 항상 함께 로드한다(개인 로컬 오버라이드 용도). 우선순위는 `.env.[mode]` > `.env.local` > `.env` 이므로, 각 env 파일에 **동일한 키 집합**을 유지하면 mode 파일 값이 항상 이긴다. 특정 mode 에만 있어야 할 키를 `.env.local` 에 두면 다른 mode 로 새어 들어갈 수 있으니 주의. > 참고: Vite 8 부터 `local` 은 모드 이름으로 사용할 수 없다(`.env.local` 의 `.local` 접미사와 충돌). 그래서 로컬 개발은 별도 모드 없이 기본 `vite`(mode: `development`)로 실행하고, 로컬 값은 `.env.local` 에 둔다 — Vite 는 `.env.local` 을 **모든 모드에서 항상 자동 로드**한다(개인 로컬 오버라이드 용도). 우선순위는 `.env.[mode]` > `.env.local` > `.env` 이므로, 각 env 파일에 **동일한 키 집합**을 유지하면 mode 파일 값이 항상 이긴다. 특정 mode 에만 있어야 할 키를 `.env.local` 에 두면 다른 mode 로 새어 들어갈 수 있으니 주의.
## 실행 / 빌드 ## 실행 / 빌드
`--mode <name>` 으로 위 표의 env 파일이 선택된다. `--mode <name>` 으로 `.env.[name]` 파일이 선택된다(로컬은 모드 없이 `.env.local` 자동 로드).
```bash ```bash
npm run dev # 로컬 개발 서버 (mode: local → .env.local) npm run dev # 로컬 개발 서버 (mode: development → .env.local 자동 로드)
npm run dev:dev # 개발 서버를 dev 환경 변수로 실행 (mode: dev → .env.dev) npm run dev:dev # 개발 서버를 dev 환경 변수로 실행 (mode: dev → .env.dev)
npm run build # 운영 빌드 (mode: prod → .env.prod), build:prod 와 동일 npm run build # 운영 빌드 (mode: prod → .env.prod), build:prod 와 동일

View File

@ -4,7 +4,7 @@
"version": "0.0.0", "version": "0.0.0",
"type": "module", "type": "module",
"scripts": { "scripts": {
"dev": "vite --mode local", "dev": "vite",
"dev:dev": "vite --mode dev", "dev:dev": "vite --mode dev",
"build": "tsc -b && vite build --mode prod", "build": "tsc -b && vite build --mode prod",
"build:dev": "tsc -b && vite build --mode dev", "build:dev": "tsc -b && vite build --mode dev",