환경 변수 설정

소프트웨어 개발에서 환경 변수(Environment Variables)는 애플리케이션 동작을 제어하고 민감 정보를 관리하는 핵심 수단입니다.

개발/테스트/운영 환경마다 설정값이 다르거나, DB 비밀번호와 API 키 같은 보안 정보를 안전하게 다뤄야 할 때 특히 중요합니다.

Next.js는 환경 변수 관리를 위한 강력하고 유연한 메커니즘을 제공해 배포와 운영을 더 안전하고 효율적으로 만들 수 있도록 돕습니다.

이 절에서는 환경 변수의 개념과 중요성, Next.js에서 환경 변수를 설정하고 사용하는 다양한 방법, 그리고 보안 및 배포 환경에 따른 최적의 환경 변수 관리 전략에 대해 상세히 알아보겠습니다.

환경 변수의 개념 및 중요성

환경 변수는 운영 체제 수준에서 설정되거나 애플리케이션 실행 시 주입되는 변수입니다.

코드 내부에 직접 값을 하드코딩하는 대신 환경 변수를 사용하는 이유는 다음과 같습니다.

• 보안: 데이터베이스 비밀번호, 서드파티 API 키, 민감한 인증 정보 등은 코드 리포지토리에 직접 노출되어서는 안 됩니다. 환경 변수를 사용하면 이러한 정보가 코드와 분리되어 안전하게 관리될 수 있습니다.
• 환경별 설정 분리: 개발 서버, 스테이징 서버, 프로덕션 서버는 각기 다른 데이터베이스 연결 문자열, API 엔드포인트 등을 가질 수 있습니다. 환경 변수를 사용하면 코드 변경 없이 각 환경에 맞는 설정을 적용할 수 있습니다.
• 유연성: 같은 코드를 환경별 값으로 실행할 수 있습니다. 서버 런타임에서 읽는 값은 프로세스를 다시 시작하거나 새 배포에 주입하면 바뀌지만, NEXT_PUBLIC_ 값과 빌드 단계에서 읽은 값은 새 빌드·배포가 필요합니다.
• 유지보수성: 설정값이 한곳에 집중되어 관리되므로, 변경이나 업데이트가 용이하며 코드의 가독성이 향상됩니다.

Next.js에서 환경 변수 설정하기

Next.js는 .env 파일을 통한 로컬 환경 변수 관리와 Vercel 플랫폼을 통한 클라우드 환경 변수 관리를 모두 지원합니다.

Next.js는 빌드 시점에 환경 변수를 번들링하는 방식과 런타임에 접근하는 방식을 모두 지원합니다.

로컬 환경 변수 (.env 파일)

로컬 개발 환경에서 환경 변수를 사용하려면 프로젝트 루트 디렉터리에 .env 파일을 생성합니다.

Next.js는 기본적으로 다음과 같은 .env 파일을 지원합니다.

• .env: 기본 환경 변수.
• .env.local: 모든 모드에서 사용할 수 있는 로컬 덮어쓰기 파일이며 test 모드에서는 로드하지 않습니다. Git에 커밋하지 않습니다.
• .env.$(NODE_ENV): .env.development, .env.production, .env.test처럼 현재 실행 모드 전용 값.
• .env.$(NODE_ENV).local: 현재 실행 모드의 로컬 덮어쓰기 값.

조회 우선순위: 이미 설정된 process.env → .env.$(NODE_ENV).local → .env.local(test 제외) → .env.$(NODE_ENV) → .env입니다.

NODE_ENV는 일반적으로 development, production, test 중 하나입니다.

next dev 명령어는 development 모드로, next build는 production 모드로 실행됩니다.

# .env.local
DATABASE_URL=mongodb://localhost:27017/my-local-db
API_SECRET_KEY=my_local_secret_key_for_server

# NEXT_PUBLIC_ 접두사가 붙은 변수는 클라이언트 측 코드에서도 접근 가능합니다.
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX
NEXT_PUBLIC_API_BASE_URL=http://localhost:3000/api

환경 변수 접근 방식

Next.js에서는 process.env로 값을 읽습니다. 아래 두 예제는 서버 전용 값과 공개 값의 사용 위치를 비교합니다.

export async function GET() {
  const dbUrl = process.env.DATABASE_URL; // 서버에서만 접근 가능

  if (!dbUrl) {
    return Response.json({ error: 'DATABASE_URL is not configured' }, { status: 500 });
  }

  return Response.json({ databaseConfigured: true });
}

"use client";

import { useEffect } from 'react';

export default function AnalyticsTracker() {
  useEffect(() => {
    const gaId = process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID;
    if (gaId) {
      // console.log(`Google Analytics ID: ${gaId}`);
      // 실제로는 여기에 GA 초기화 스크립트가 들어갑니다.
    }
  }, []);

  return null;
}

Vercel을 이용한 클라우드 환경 변수 설정

Vercel은 배포 환경(Development, Preview, Production)에 따라 환경 변수를 안전하고 효율적으로 관리할 수 있는 UI를 제공합니다.

Vercel 대시보드에서 환경 변수 추가

Vercel 환경 변수의 동작 방식

• Vercel에 설정된 환경 변수는 선택한 환경 범위에 따라 빌드 프로세스와 배포된 서버 함수에서 사용할 수 있습니다.
• Production 환경 변수: main 브랜치 또는 기본 프로덕션 브랜치에 푸시되어 배포될 때 사용됩니다.
• Preview 환경 변수: 미리보기 배포의 빌드와 서버 처리에 사용됩니다. 운영 데이터에 영향을 주지 않도록 별도 백엔드 값을 설정합니다.
• Development 환경 변수: vercel dev로 실행하면 Vercel CLI가 로컬 프로젝트 설정과 Development 값을 사용합니다. 일반 next dev에서 같은 값을 쓰려면 먼저 vercel env pull로 환경 파일을 만들거나 vercel env run -- next dev로 주입합니다.

Vercel에 저장한 변경은 기존 배포를 바꾸지 않으며 다음 배포부터 적용됩니다.

값이 선택되는 과정을 확인하기 NODE_ENV=test이고 프로세스에는 DATABASE_URL이 없다고 합시다. .env.local에는 로컬 DB 주소, .env.test에는 테스트 DB 주소가 있습니다. 원 GET 예제는 어느 값을 읽을까요? 이어서 실행 전에 프로세스에 DATABASE_URL=not-a-database-url을 넣었다면 상태 코드와 본문은 무엇일까요?

배포된 공개 값 확인하기 NEXT_PUBLIC_API_BASE_URL을 A 주소로 빌드한 뒤 대시보드에서 B로 바꾸고 기존 배포의 브라우저를 새로 고치면 어느 값을 사용할까요? 원 AnalyticsTracker에 ID만 넣으면 방문 기록도 전송될까요?

환경 변수 관리 모범 사례 및 보안 팁

• 민감 정보는 NEXT_PUBLIC_ 접두사 없이 사용: 데이터베이스 자격 증명, 서버 API 키 등 민감한 정보는 반드시 클라이언트 측에 노출되지 않도록 NEXT_PUBLIC_ 접두사 없이 사용해야 합니다.
• .env.local은 .gitignore에 포함: 로컬 개발용 .env.local 파일은 실수로 Git 리포지토리에 커밋되지 않도록 .gitignore 파일에 반드시 추가해야 합니다.
• 환경 변수 이름 규칙: 명확하고 일관성 있는 이름 지정 규칙을 사용합니다 (예: DB_HOST, API_URL, STRIPE_SECRET_KEY).
• 각 환경에 맞는 값 설정: 개발, 테스트, 운영 환경에 따라 적절한 환경 변수 값을 설정하여 실수로 프로덕션 데이터베이스에 개발 데이터를 쓰는 등의 문제를 방지합니다.
• 공개 값의 참조 방식: process.env.NEXT_PUBLIC_NAME처럼 직접 참조해야 빌드 시 인라인됩니다. 변수 이름을 계산하는 process.env[name]이나 process.env 별칭은 같은 방식으로 인라인되지 않습니다.
• CI/CD 파이프라인에서 환경 변수 관리: GitHub Actions, GitLab CI/CD 등 CI/CD 파이프라인을 사용하는 경우, 해당 서비스의 비밀 변수(Secrets) 관리 기능을 통해 환경 변수를 안전하게 주입해야 합니다. Vercel Git 배포는 Vercel 프로젝트에 등록한 값을 사용합니다. GitHub Actions 등의 Secrets가 Vercel 환경 변수로 자동 복사되는 것은 아닙니다.
• 보안 감사: 정기적으로 환경 변수 설정과 사용 방식을 검토하여 불필요한 노출이나 보안 취약점이 없는지 확인합니다.

환경별 값이 올바른지는 변수의 존재 여부뿐 아니라 실제 기능의 응답을 통해 확인합니다. 로그에는 비밀값 자체를 남기지 않습니다.