Next.js 환경 변수 & 설정

Next.js에서 환경 변수(Environment Variables)는
단순 설정값이 아니라 보안, 배포, 환경 분리를 담당하는 핵심 요소이다.

특히 Next.js는 Server와 Client가 함께 존재하기 때문에
환경 변수의 사용 범위를 명확히 구분해야 한다.

---

1. .env.local

Next.js에서는 .env.local 파일을 통해 환경 변수를 관리한다.

NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_APP_ENV=development

DATABASE_URL=postgres://user:password@localhost:5432/db
JWT_SECRET=super-secret-key

특징

• 로컬 환경에서만 사용
• Git에 포함되지 않음 (.gitignore)
• 민감 정보(API Key, DB 정보) 분리 가능

---

환경 파일 종류

파일명	용도
.env	기본 환경
.env.local	로컬 전용
.env.development	개발 환경
.env.production	배포 환경

---

우선순위

.env.local > .env.development > .env

---

실무 기준

• 로컬: .env.local 사용
• 배포: 플랫폼(Vercel 등)에 직접 설정

---

2. process.env 사용법

환경 변수는 process.env로 접근한다.

const apiUrl = process.env.NEXT_PUBLIC_API_URL;

---

핵심 규칙

1. 클라이언트에서 사용하려면 NEXT_PUBLIC_ 필요

NEXT_PUBLIC_API_URL=...

→ 브라우저에서 접근 가능

---

2. prefix 없는 변수는 서버 전용

JWT_SECRET=...

→ 서버에서만 사용 가능

---

왜 이런 구조일까?

Next.js는 클라이언트 코드를 브라우저로 번들링한다.

• NEXT_PUBLIC_ → 번들에 포함됨
• 일반 변수 → 서버에만 존재

→ 잘못 사용하면 비밀 정보가 그대로 노출됨

---

3. 실행 환경 (Server vs Client)

Next.js는 코드 실행 위치에 따라 동작이 달라진다.

---

Server Side

• Node.js에서 실행
• 모든 환경 변수 접근 가능

export async function getServerSideProps() {
  const db = process.env.DATABASE_URL;
}

---

Client Side

• 브라우저에서 실행
• NEXT_PUBLIC_ 변수만 접근 가능

useEffect(() => {
  fetch(process.env.NEXT_PUBLIC_API_URL);
}, []);

---

핵심

→ 같은 코드라도 실행 위치에 따라 결과가 달라진다

---

4. 환경 변수 로딩 시점

환경 변수는 빌드 및 서버 시작 시점에 로딩된다

---

특징

• 실행 중 변경 불가
• 변경 후 서버 재시작 필요

npm run dev

---

5. 실무 패턴

API 주소 분리

# 개발
NEXT_PUBLIC_API_URL=http://localhost:3000

# 배포
NEXT_PUBLIC_API_URL=https://api.myapp.com

---

환경 구분

NEXT_PUBLIC_APP_ENV=development

if (process.env.NEXT_PUBLIC_APP_ENV === "development") {
  console.log("dev mode");
}

---

서버 전용 변수

JWT_SECRET=...
DATABASE_URL=...

→ NEXT_PUBLIC_ 붙이지 않기

---

6. 보안 원칙

잘못된 예:

const secret = process.env.JWT_SECRET;

→ 클라이언트 코드에서 사용 시 노출 위험

---

올바른 방식:

• 비밀 값 → 서버에서만 사용
• 클라이언트 → API 호출만 수행

---

7. 디버깅 체크리스트

• NEXT_PUBLIC_ prefix 확인
• 서버 재시작 여부
• 변수명 오타
• .env.local 위치 확인

---

8. 배포 시 주의사항

• .env.local은 배포 서버에 포함되지 않음
• 환경 변수는 배포 플랫폼에 직접 등록해야 함

---

정리

• 환경 변수는 실행 환경에 따라 접근 범위가 다르다
• 클라이언트에서는 NEXT_PUBLIC_ 필수
• 민감 정보는 서버에서만 처리
• 환경 변수는 빌드/실행 시점에 적용된다