Choorai
| 문서
자주 발생하는 에러

환경 변수 에러 해결하기

"process.env.API_KEY is undefined" 에러가 발생했나요? 환경 변수가 제대로 설정되지 않았을 때 발생합니다.

TL;DR (핵심 요약)

1) .env 파일 생성 2) 변수 앞에 VITE_ 또는 NEXT_PUBLIC_ 접두사 추가 3) 서버 재시작

주의

process.env.API_KEY is undefined

원인

환경 변수가 설정되지 않았거나, 프론트엔드에서 접근 불가능한 변수를 사용했습니다.

해결책
  1. 프로젝트 루트에 .env 파일을 생성하세요
  2. Vite: 변수명 앞에 VITE_ 접두사를 붙이세요
  3. Next.js: 변수명 앞에 NEXT_PUBLIC_ 접두사를 붙이세요
  4. 서버를 재시작하세요

프레임워크별 설정 방법

Vite React + Vite

.env
# 프론트엔드에서 접근 가능 (VITE_ 접두사 필수!)
VITE_API_URL=https://api.example.com
VITE_PUBLIC_KEY=pk_test_xxx

# 프론트엔드에서 접근 불가 (서버 전용)
DATABASE_URL=postgres://...
SECRET_KEY=your-secret

사용법: import.meta.env.VITE_API_URL

Next.js

.env.local
# 프론트엔드에서 접근 가능 (NEXT_PUBLIC_ 접두사 필수!)
NEXT_PUBLIC_API_URL=https://api.example.com

# 서버 전용
DATABASE_URL=postgres://...

사용법: process.env.NEXT_PUBLIC_API_URL

Python FastAPI

.env
DATABASE_URL=postgres://user:pass@localhost/db
SECRET_KEY=your-secret-key
DEBUG=true
config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    secret_key: str
    debug: bool = False

    class Config:
        env_file = ".env"

settings = Settings()

.gitignore에 추가하세요!

.env 파일에는 민감한 정보가 들어갑니다. 반드시 .gitignore에 추가해서 GitHub에 업로드되지 않도록 하세요.

.gitignore
# 환경 변수 파일
.env
.env.local
.env.*.local

관련 문서