환경 변수 (.env)란?

Next.js 프로젝트에서 환경 별 값을 설정하는 변수 값
API_KEY, DB_URL, SECRET 등 민감한 정보는 코드에 직접 작성하는 대신 환경변수를 통해 안전하게 관리

• 구성
  

---

1. 환경변수 파일 종류

Next.js는 환경에 따라 아래와 같은 파일을 자동 인식:

파일명	설명
.env	기본 환경변수 (모든 환경에서 공통으로 사용)
.env.local	로컬 개발용 환경변수 (Git에 커밋하지 않음)
.env.development	next dev 실행 시 사용
.env.production	next build & next start 실행 시 사용
.env.test	테스트 환경에서 사용

.env.local은 Git에 커밋하면 안 됨. (.gitignore에 기본 포함됨)

---

2. 환경변수 선언 예시

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
SECRET_KEY=my-secret-key

3. Next.js 환경변수 네이밍 규칙

Next.js에서는 환경변수를 선언할 때 접근 범위에 따라 변수명 규칙이 존재.

---

• 클라이언트에서 접근 가능한 변수: NEXT_PUBLIC_ 접두사 필수
• 나머지는 서버 사이드에서만 접근 가능.

변수명 / 접근 가능 위치
NEXT_PUBLIC_*	✅ 클라이언트 & 서버 모두
일반 변수 (SECRET_KEY, DB_URL 등)	✅ 서버 전용 ❌ 클라이언트 불가

4. 환경변수 사용 방법 (Next.js 기준)

Next.js에서는 process.env.변수명으로 환경변수를 사용할 수 있습니다.
서버/클라이언트 위치에 따라 접근 방식이 다르며, NEXT_PUBLIC_ 접두사가 중요.

---

4-1. 서버 컴포넌트 또는 API Route에서 사용

.env 또는 .env.local에 선언한 환경변수는 서버 코드에서 바로 사용가능.

# .env.local
SECRET_KEY=my-secret

// app/api/hello/route.ts
export async function GET() {
  const secret = process.env.SECRET_KEY
  return Response.json({ secret })
}

• SECRET_KEY는 클라이언트 코드에서는 접근할 수 없습니다. (보안 상 안전)

4-2. 클라이언트 컴포넌트에서 사용 (NEXT_PUBLIC_ 붙이기)

클라이언트 컴포넌트에서 환경변수를 사용하려면 반드시 NEXT_PUBLIC_ 접두사가 필요.

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com

// app/components/ClientComponent.tsx
"use client"

export default function ClientComponent() {
  const apiUrl = process.env.NEXT_PUBLIC_API_URL
  return <p>API 주소: {apiUrl}</p>
}

process.env.API_URL처럼 접두사가 없는 변수는 브라우저에서는 undefined로 나옵니다.

4-3. TypeScript에서 환경변수 타입 지정 (선택)

• process.env는 기본적으로 모든 키를 string | undefined로 간주하므로 타입 오류가 날 수 있음.
  이럴 땐 env.d.ts로 타입을 정의할 수 있음.

// env.d.ts
namespace NodeJS {
  interface ProcessEnv {
    NEXT_PUBLIC_API_URL: string
    SECRET_KEY: string
  }
}

• env.d.ts 파일 정의 후, tsconfig.json 설정 확인

{
  "compilerOptions": {
    "strict": true,
    "types": []
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    "env.d.ts",        // ✅ 여기에 직접 경로 추가
    "types/env.d.ts"   // ✅ types 폴더에 뒀다면 이렇게
  ]
}

4-4. 환경변수 변경 시 dev 서버 재시작 필수

.env 파일을 수정한 경우에는 반드시 dev 서버를 재시작해야 반영 됨.

npm run dev

5. 클라이언트에 노출되면 안 되는 정보 예시

• 데이터베이스 주소 (DATABASE_URL)
• 시크릿 키 (SECRET_KEY)
• 외부 API 키 중 민감한 키 (예: Stripe Secret Key)

이런 값들은 절대 NEXT_PUBLIC_을 붙이지 않고, 서버에서만 사용해야 함.

6. 정리

• .env는 프로젝트 루트에 위치
• 클라이언트에서 사용하려면 반드시 NEXT_PUBLIC_ 접두사 붙이기
• 민감 정보는 .env.local에 작성 & Git에 커밋하지 않기
• 환경에 따라 .env.production, .env.development 분리 가능