Next.js에서 환경 변수는 어떻게 동작하나요?

Question

Accepted Answer

Next.js는 `.env` 파일에서 환경 변수를 로드하며, 중요한 보안 규칙이 있습니다. 변수는 **기본적으로 서버 전용**이고, `NEXT_PUBLIC_`으로 시작하는 것만 브라우저에 노출됩니다.

## 파일들

```text
.env                # 모든 환경에서 로드됨
.env.local          # 로컬 재정의 — GITIGNORE됨 (비밀 정보를 여기 둠)
.env.development    # `next dev`에서만
.env.production     # 프로덕션 빌드에서만
```

## 핵심 접두사 규칙

```bash
# .env.local
DATABASE_URL=postgres://...secret...   # 서버 전용 — 브라우저로 절대 전송되지 않음
NEXT_PUBLIC_API_URL=https://api.example.com  # 브라우저에 노출됨
```

```tsx
// Server Component / Route Handler / Server Action — 무엇이든 읽을 수 있음
const db = process.env.DATABASE_URL;          // ✅ 서버에서 동작

// Client Component — NEXT_PUBLIC_* 만 사용 가능
"use client";
const api = process.env.NEXT_PUBLIC_API_URL;  // ✅ 동작
const secret = process.env.DATABASE_URL;      // ❌ 브라우저에서는 undefined
```

이 접두사 규칙은 **보안 기능**입니다. 데이터베이스 비밀번호나 API 비밀 키를 실수로 클라이언트로 보내는 것을 방지합니다. 접두사가 없는 변수는 브라우저 번들에 아예 존재하지 않습니다.

## NEXT_PUBLIC 값이 포함되는 방식

```text
NEXT_PUBLIC_* 은 빌드 시점에 인라인됨 (JS 번들에 구워짐).
```

빌드 시점에 인라인되기 때문에 `NEXT_PUBLIC_` 값을 변경하려면 **재빌드**가 필요합니다. 그리고 진짜 비밀 정보는 절대 접두사 뒤에 두지 마세요(번들에서 누구나 볼 수 있게 됩니다).

## 모범 사례

```text
✓ 비밀 정보(DB URL, API 키) → 접두사 없음, 서버 측 유지, .env.local에 (gitignore됨)
✓ 공개 설정(공개 API 베이스, analytics id) → NEXT_PUBLIC_
✓ 필요한 변수를 문서화하는 .env.example 커밋 (실제 값 없이)
```

## 왜 중요한가

`NEXT_PUBLIC_` 옵트인과 함께하는 서버 전용 기본 모델은 비밀 정보가 클라이언트로 새어 나가는 것을 막는 Next.js의 가드레일입니다. 흔하고 심각한 실수죠.

어떤 변수가 브라우저에 도달하는지, 공개 변수는 빌드 시점에 인라인된다는 점, 비밀 정보를 어디에 저장해야 하는지(gitignore된 `.env.local`)를 이해하는 것은 기능과 보안 모두에 필수적입니다.