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

Prerequisites

  • 프로젝트 루트의 .env 파일을 수정할 수 있어야 합니다.
  • 현재 프레임워크(Vite/Next.js/FastAPI)와 실행 모드를 알고 있어야 합니다.
  • 서버 재시작 후 로그를 확인할 수 있어야 합니다.

Validation

  1. Vite는 import.meta.env.VITE_* 값이 정상 출력됩니다.
  2. Next.js는 process.env.NEXT_PUBLIC_* 값이 브라우저에서 확인됩니다.
  3. 민감한 서버 전용 키는 클라이언트 번들에 포함되지 않습니다.

Troubleshooting

  • .env 파일 위치가 프로젝트 루트인지 다시 확인하세요.
  • 변수명 접두사(VITE_, NEXT_PUBLIC_) 누락 여부를 확인하세요.
  • 개발 서버/빌드 프로세스를 재시작하고 다시 확인하세요.

References

관련 문서

마지막 업데이트: 2026년 2월 22일 · 버전: v0.0.1

피드백 보내기

입력한 내용으로 새 이슈 페이지를 엽니다.

GitHub 이슈로 보내기