---
task_id: task-2120
type: context
scope: task
created: 2026-04-23
updated: 2026-04-23
status: in-progress
---

# 맥락 노트: task-2120

**task**: task-2120

---

## 결정 근거

### 방법 A+B 조합 채택

- Cloudflare Pages는 환경변수를 `process.env`에 설정하지만, Vite는 `.env` 파일 기반으로 `import.meta.env`를 치환
- task-2115에서 `.env`를 git에서 제거했으므로 CI 빌드 시 `.env` 파일이 없음
- 방법 A (vite.config.ts define): Cloudflare Pages의 `process.env` 환경변수를 빌드 시점에 `import.meta.env`로 명시적 매핑
- 방법 B (.env.production): 로컬 빌드/CI fallback용 공개 URL 설정. git 추적하여 `.env` 없이도 프로덕션 URL 사용 가능
- A만 사용 시: Cloudflare 환경변수 미설정 시 빈 문자열 → B가 fallback 역할
- B만 사용 시: process.env에서 동적 주입 불가 → A가 동적 매핑 역할

### 3 Step Why 자문

1st Why: "왜 이 설계가 필요한가?"
→ Vite는 빌드 시점에 import.meta.env를 정적 치환하는데, Cloudflare Pages의 process.env를 자동으로 읽지 않음. 명시적 매핑 없이는 환경변수가 빌드에 반영 불가.

2nd Why: "왜 A+B 조합이 최선의 접근인가?"
→ A만으로는 Cloudflare 환경변수 미설정 시 빈 문자열이 됨. B만으로는 환경변수 오버라이드가 불가. 조합하면 .env.production이 기본값, process.env가 오버라이드하는 계층적 구조가 됨.

3rd Why: "왜 이 접근이 다른 대안보다 나은가?"
→ 방법 C(빌드 명령어 변경)는 Cloudflare Pages 대시보드 의존적이고 변수 추가 시마다 빌드 명령어 수정 필요. A+B는 코드 레벨에서 완결되어 유지보수가 용이.

## 참조 자료

- 태스크 파일: `/home/jay/workspace/memory/tasks/task-2120.md`
- vite.config.ts: `/home/jay/projects/InsuRo/vite.config.ts`
- api.ts: `/home/jay/projects/InsuRo/src/config/api.ts`
- Vite 환경변수 문서: https://vitejs.dev/guide/env-and-mode.html

## 주의사항

- .env.production에는 공개 가능한 URL만 포함 (API 키, 시크릿 제외)
- .env 파일은 .gitignore에 유지 (민감정보 포함 가능)
- vite.config.ts의 define에서는 VITE_ 접두사 변수만 매핑 (보안 관행)