🌍 Next.js 환경 변수 설정 가이드

🌍 Next.js 환경 변수 설정 가이드

Next.js에서는 환경 변수를 통해 다양한 환경에 맞춰 설정 값을 관리할 수 있습니다.
개발, 테스트, 프로덕션 환경에 따라 각기 다른 변수 값을 지정하여 유연한 애플리케이션 구성이 가능합니다.

---

✅ 1. 기본 환경 변수 설정

환경 변수 파일 구조

Next.js에서는 다음과 같은 파일 이름으로 환경 변수를 관리할 수 있습니다:

.env                # 기본 환경 (개발)
.env.local          # 로컬 환경 (Git에 추가하지 않음)
.env.development    # 개발 환경
.env.production     # 프로덕션 환경
.env.test           # 테스트 환경

환경 변수 파일 예시

.env

NEXT_PUBLIC_API_URL=https://api.example.com
SECRET_KEY=mysecretkey

환경 변수 사용

Next.js에서는 process.env 객체를 통해 환경 변수를 불러올 수 있습니다.

// app/page.tsx
export default function HomePage() {
  return (
    <div>
      <h1>API URL: {process.env.NEXT_PUBLIC_API_URL}</h1>
    </div>
  );
}

---

✅ 2. 환경 변수명 규칙

반응형

Next.js에서 클라이언트에서 접근 가능한 변수는 반드시 NEXT_PUBLIC_ 접두어를 사용해야 합니다.
접두어 없이 선언된 변수는 서버 측에서만 접근 가능합니다.

올바른 예

NEXT_PUBLIC_ANALYTICS_ID=123456

잘못된 예

API_SECRET_KEY=mysecretkey   # 클라이언트에서 접근 불가

---

✅ 3. 환경 변수 로딩 순서

1. .env.local
2. .env.development, .env.production, .env.test
3. .env

주의:
.env.local은 항상 가장 우선시 되며, 버전 관리에서 제외해야 합니다.
.env.production 파일은 프로덕션 빌드 시에만 사용됩니다.

---

✅ 4. 서버에서 사용하기

서버 전용 환경 변수는 NEXT_PUBLIC_ 접두어 없이 설정할 수 있습니다.

DATABASE_URL=postgres://user:pass@localhost:5432/mydb

사용 예시

// app/api/data/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  const dbUrl = process.env.DATABASE_URL;
  return NextResponse.json({ url: dbUrl });
}

---

✅ 5. 클라이언트에서 사용하기

클라이언트 컴포넌트에서는 NEXT_PUBLIC_ 접두어를 반드시 사용해야 합니다.

// app/page.tsx
export default function HomePage() {
  return (
    <div>
      <h2>API Endpoint: {process.env.NEXT_PUBLIC_API_URL}</h2>
    </div>
  );
}

---

✅ 6. 환경 변수 설정 방법

개발 환경

npm run dev

프로덕션 환경

npm run build
npm start

빌드 시 환경 변수 설정

빌드 시 환경 변수를 명시적으로 지정할 수 있습니다.

NEXT_PUBLIC_API_URL=https://api.prod.com npm run build

런타임 시 환경 변수 설정

NEXT_PUBLIC_API_URL=https://api.prod.com npm start

---

✅ 7. Vercel 환경 변수 설정

Vercel에 배포할 때는 Vercel 대시보드에서 환경 변수를 설정할 수 있습니다.

1. 프로젝트 선택
2. Settings → Environment Variables
3. 키와 값을 입력하고 저장

배포 후 환경 변수를 변경할 경우 재배포가 필요합니다.

---

✅ 8. 문제 해결

환경 변수가 안 보일 때

1. 환경 변수 이름 앞에 NEXT_PUBLIC_가 없는 경우
2. 빌드 후 값이 반영되지 않은 경우
3. .env.local 파일이 없는 경우

확인 방법

npm run build && npm start

브라우저에서 다음을 확인합니다:

API URL: https://api.prod.com

---

✅ 9. 보안 고려 사항

• 클라이언트 노출 방지: 민감한 정보는 NEXT_PUBLIC_ 없이 설정하여 서버 전용으로 사용
• 환경 변수 관리: 로컬 개발과 프로덕션 환경을 구분하여 관리
• 비밀키 관리: .env.local은 Git에 커밋되지 않도록 .gitignore에 추가

.gitignore

.env.local

---

✅ 요약

항목 설명

환경 변수 파일 구조	.env, .env.local, .env.development 등 관리
클라이언트 접근	NEXT_PUBLIC_ 접두어 필수
서버 전용 변수	접두어 없이 사용 가능
Vercel 배포 설정	Vercel 대시보드에서 환경 변수 설정 가능
보안 고려 사항	민감 정보는 NEXT_PUBLIC_ 접두어 사용 금지

---

 

Next.js, 환경 변수, 환경 설정, 환경 변수 관리, 클라이언트 환경 변수, 서버 환경 변수, Vercel 환경 변수, 환경 변수 보안, 설정 파일 관리, 환경 변수 디버깅