10장: 환경 변수와 설정

alpha2025-04-30 01:39

환경 변수란 무엇이고 왜 필요할까?

웹 개발을 하다 보면 외부 API 키, 데이터베이스 주소, 서비스 이름 등 민감하거나 환경별로 달라지는 정보를 소스 코드가 아니라 별도로 관리해야 할 때가 많습니다. 이런 정보를 바로 코드에 박아두면 보안상 문제가 생기고, 개발·테스트·운영 환경마다 설정값을 매번 바꿔야 하는 번거로움도 커집니다. Next.js에서는 이런 문제 해결을 위해 ‘환경 변수’ 시스템을 기본 제공합니다.

Next.js 15의 환경 변수 구조

Next.js 15에서는 .env 파일 기반 환경 변수 관리가 표준입니다. 프로젝트 루트에 .env.local, .env.development, .env.production 파일을 두고 환경별로 다른 값을 쉽게 적용할 수 있습니다. 예를 들어 실제 서비스에서는 외부 결제 API 키를, 개발 환경에서는 테스트용 키를 쓴다면 각각의 파일에 맞는 값을 설정하는 식입니다.

.env.local: 항상 가장 우선으로 읽히며, 기밀 정보나 개인 개발 설정에 권장됩니다.
.env.development: 개발 서버 실행 시 적용
.env.production: 프로덕션 빌드시 적용

파일에 다음과 같이 작성해 둡니다.

API_URL=https://api.example.com
DB_USER=devuser
DB_PASS=devpass
NEXT_PUBLIC_APP_NAME=MyNextApp

설정한 변수는 코드 내에서 process.env.API_URL 형태로 사용할 수 있습니다.

환경 변수의 구분과 보안

Next.js에서는 환경 변수명을 통해 변수의 노출 범위를 자동으로 관리합니다. 특히 이름 앞에 NEXT_PUBLIC_을 붙인 변수만 클라이언트(브라우저) 코드에서 읽을 수 있습니다. 예를 들어, NEXT_PUBLIC_ANALYTICS_ID처럼 지정하면 서버와 브라우저 모두 접근 가능하지만, 그 외 변수는 서버 코드에서만 사용됩니다. API 키나 데이터베이스 정보처럼 민감한 값에는 프리픽스를 붙이지 않아야 합니다.

next.config.js를 이용한 환경 변수 적용

추가로, 환경 변수 값을 Next.js 전역 설정에 반영해야 할 경우엔 next.config.js의 env 옵션을 적극 활용할 수 있습니다. 예시는 아래와 같습니다.

// next.config.js
module.exports = {
  env: {
    API_URL: process.env.API_URL,
    NEXT_PUBLIC_APP_NAME: 'My Next.js App',
  },
};

이렇게 하면 코드 전반에서 변수값을 직접 선언하지 않고도 일관적으로 사용할 수 있습니다.

환경별 변수, git에 안전하게 관리하기

환경 변수 파일 중 .env.local은 개인 설정과 민감 정보를 담기에 좋지만, 깃(Git)에는 올리지 않아야 안전합니다. 필요한 경우 .gitignore에 .env.local을 반드시 추가해 저장소에 노출되지 않게 관리하세요.

환경 변수 적용의 실전 예시

실제로 환경 변수를 활용하는 예시를 보면 더욱 명확합니다. 예를 들어 외부 API 주소를 환경 변수로 지정할 경우:

// 예시: fetch 함수에서 API_URL 사용
fetch(`${process.env.API_URL}/products`)

개발과 운영 환경 모두에서 소스 코드는 변하지 않고, 환경 변수 값만 다르게 적용하면 됩니다.

마무리: 유지보수와 보안을 위한 필수 습관

정리하자면, Next.js의 환경 변수 시스템은 코드의 유연성과 보안을 모두 챙길 수 있게 해줍니다. 환경별로 분리된 변수 파일, 클라이언트-서버 코드 구분을 명확히 하는 네이밍 규칙, 그리고 안전한 파일 관리까지 익혀두면 실전 프로젝트에서 큰 실수를 막을 수 있습니다. 다음 장에서는 프로젝트를 더욱 개성 있게 만드는 설정과 확장 테크닉을 이어서 살펴보겠습니다.