환경 변수 설정

소프트웨어 개발에서 환경 변수(Environment Variables) 는 애플리케이션의 동작을 제어하거나 민감한 정보를 저장하는 데 사용되는 핵심적인 요소입니다. 특히, 개발, 테스트, 운영 등 각기 다른 배포 환경에서 설정값이 달라지거나, 데이터베이스 비밀번호, API 키와 같은 보안에 민감한 정보를 안전하게 관리해야 할 때 필수적입니다. Next.js는 환경 변수 관리를 위한 강력하고 유연한 메커니즘을 제공하여, 개발자가 안전하고 효율적으로 애플리케이션을 배포하고 관리할 수 있도록 돕습니다.

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

환경 변수의 개념 및 중요성

환경 변수는 운영 체제 수준에서 설정되거나 애플리케이션 실행 시 주입되는 변수입니다. 코드 내부에 직접 값을 하드코딩하는 대신 환경 변수를 사용하는 이유는 다음과 같습니다.

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

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

Next.js는 .env 파일을 통한 로컬 환경 변수 관리와 Vercel 플랫폼을 통한 클라우드 환경 변수 관리를 모두 지원합니다. Next.js는 빌드 시점에 환경 변수를 번들링하는 방식과 런타임에 접근하는 방식을 모두 지원합니다.

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

로컬 개발 환경에서 환경 변수를 사용하려면 프로젝트 루트 디렉토리에 .env 파일을 생성합니다. Next.js는 기본적으로 다음과 같은 .env 파일을 지원합니다.

• .env: 기본 환경 변수.
• .env.local: 로컬 개발 전용 환경 변수. Git에 커밋되지 않도록 .gitignore에 추가하는 것이 강력히 권장됩니다. Vercel 배포 시에는 이 파일이 사용되지 않습니다.
• .env.development: 개발 환경 전용 환경 변수.
• .env.production: 프로덕션 환경 전용 환경 변수.

우선순위: .env.local > .env.[mode] > .env

.[mode]: development 또는 production을 의미합니다. next dev 명령어는 development 모드로, next build는 production 모드로 실행됩니다.

예시: .env.local 파일

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

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

환경 변수 접근 방식

Next.js에서 환경 변수는 process.env 객체를 통해 접근합니다. 이때, 클라이언트 측 번들에 포함될지 여부에 따라 접두사 사용 규칙이 있습니다.

// app/api/products/route.ts (API 라우트)
export async function GET(request: Request) {
  const dbUrl = process.env.DATABASE_URL; // 서버에서만 접근 가능

  // ... DB 연결 로직 ...
}

// components/AnalyticsTracker.tsx (Client Component)
"use client";

import { useEffect } from 'react';

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

  return null;
}

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

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

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

Vercel 환경 변수의 동작 방식

• Vercel에 설정된 환경 변수는 배포 시 Next.js 빌드 프로세스에 주입됩니다.
• Production 환경 변수: main 브랜치 또는 기본 프로덕션 브랜치에 푸시되어 배포될 때 사용됩니다.
• Preview 환경 변수: 개발 브랜치에서 Pull Request가 생성되어 미리보기 배포가 될 때 사용됩니다. 이를 통해 새로운 기능이 프로덕션에 영향을 주기 전에 실제 백엔드와 연동 테스트를 할 수 있습니다.
• Development 환경 변수: vercel dev 명령어로 Vercel CLI를 통해 로컬에서 개발 서버를 실행할 때 사용됩니다. 로컬 .env.local 파일이 없는 경우 Vercel에 설정된 Development 변수를 가져옵니다.

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

• 민감 정보는 NEXT_PUBLIC_ 접두사 없이 사용: 데이터베이스 자격 증명, 서버 API 키 등 민감한 정보는 반드시 클라이언트 측에 노출되지 않도록 NEXT_PUBLIC_ 접두사 없이 사용해야 합니다.
• .env.local은 .gitignore에 포함: 로컬 개발용 .env.local 파일은 실수로 Git 리포지토리에 커밋되지 않도록 .gitignore 파일에 반드시 추가해야 합니다.
• 환경 변수 이름 규칙: 명확하고 일관성 있는 이름 지정 규칙을 사용합니다 (예: DB_HOST, API_URL, STRIPE_SECRET_KEY).
• 각 환경에 맞는 값 설정: 개발, 테스트, 운영 환경에 따라 적절한 환경 변수 값을 설정하여 실수로 프로덕션 데이터베이스에 개발 데이터를 쓰는 등의 문제를 방지합니다.
• 환경 변수 주입 시점 이해: Next.js 환경 변수는 빌드 시점(Build Time) 에 번들링됩니다. 즉, 환경 변수를 변경했다면 반드시 애플리케이션을 다시 빌드하고 배포해야 변경된 값이 적용됩니다. 런타임에 동적으로 변경되는 환경 변수를 사용하려면, Next.js의 runtimeConfig 옵션이나 별도의 서버 사이드 API를 통해 값을 제공하는 방법을 고려할 수 있지만, 일반적인 process.env 사용 방식과는 다릅니다.
• CI/CD 파이프라인에서 환경 변수 관리: GitHub Actions, GitLab CI/CD 등 CI/CD 파이프라인을 사용하는 경우, 해당 서비스의 비밀 변수(Secrets) 관리 기능을 통해 환경 변수를 안전하게 주입해야 합니다. Vercel은 Git 연동 시 이를 자동으로 처리합니다.
• 보안 감사: 정기적으로 환경 변수 설정과 사용 방식을 검토하여 불필요한 노출이나 보안 취약점이 없는지 확인합니다.

환경 변수는 현대 웹 애플리케이션 개발에서 없어서는 안 될 중요한 부분입니다. Next.js와 Vercel이 제공하는 강력한 환경 변수 관리 기능을 통해 애플리케이션의 보안을 강화하고, 효율적인 배포 워크플로우를 구축할 수 있습니다.