비밀 정보 관리와 환경 변수

React 애플리케이션에서 환경 변수는 두 가지 분류로 나뉩니다. 서버 측 변수는 브라우저로 전송되지 않고, 클라이언트 측 변수는 JavaScript 번들에 포함됩니다. 변수의 분류를 이해하는 것이 비밀 정보 관리의 첫 단계입니다. 클라이언트 측 변수는 번들이 배포되면 사실상 공개되기 때문입니다.

Vite 프로젝트에서는 VITE_ 접두사가 붙은 변수만 클라이언트 번들에 포함됩니다. VITE_PUBLIC_API_URL=https://api.example.com은 import.meta.env.VITE_PUBLIC_API_URL을 통해 브라우저 코드에서 사용할 수 있습니다. 다른 모든 변수는 빌드 시 번들에서 제거되어 서버 전용으로 남습니다.

Next.js에서는 NEXT_PUBLIC_ 접두사가 변수를 브라우저 JavaScript에 노출합니다. NEXT_PUBLIC_ANALYTICS_ID=UA-123은 클라이언트 번들에 포함됩니다. 접두사가 없는 변수(예: DATABASE_URL)는 서버 측 코드(Server Components, API routes, Server Actions)에서만 사용할 수 있으며 브라우저로 전송되지 않습니다.

접두사가 없는 변수도 실수로 직렬화하면 접근할 수 있습니다. 예를 들어 Server Component가 전체 구성 객체를 Client Component에 프롭으로 전달하고 그 구성에 DATABASE_URL이 포함되어 있다면, 해당 비밀 정보가 브라우저로 전송되는 HTML에 나타납니다. 신중한 프롭 전달과 직렬화 감사를 통해 이를 방지할 수 있습니다.

다음 항목은 클라이언트 번들에 절대 포함되어서는 안 됩니다. 데이터베이스 연결 문자열과 비밀번호, 타사 API 비밀 키(Stripe 비밀 키, OpenAI API 키), 개인 RSA/EC 키, JWT 서명 비밀, 내부 서비스 인증 토큰입니다. API 호출에 이러한 항목이 필요하다면 서버 엔드포인트를 통해 해당 호출을 프록시하십시오.

프런트엔드를 위한 백엔드(BFF) 패턴은 React 앱과 민감한 외부 서비스 사이에 얇은 서버 계층을 둡니다. 클라이언트가 /api/stripe/charge를 호출하면 BFF 서버가 Stripe 비밀 키를 추가하여 Stripe API를 호출하고, BFF는 필요한 응답 데이터만 반환합니다. 비밀 정보는 영구적으로 서버에 보관됩니다.

dotenv-vault는 .env 파일을 암호화하고, 평문 비밀 정보를 버전 관리에 저장하지 않고도 환경 간에 안전하게 공유하고 배포할 수 있게 합니다. 프로덕션 대안으로는 HashiCorp Vault(엔터프라이즈), AWS Parameter Store(SSM), GCP Secret Manager가 있으며, 모두 빌드 시점이 아니라 실행 시점에 API를 통해 비밀 정보를 가져올 수 있도록 합니다.

CI/CD 플랫폼(GitHub Actions, GitLab CI)은 빌드 중 환경 변수로 사용할 수 있는 암호화된 비밀 정보 저장소를 제공합니다. 비밀 정보는 GitHub Secrets에 저장하고 워크플로에서 ${{ secrets.STRIPE_SECRET_KEY }}로 참조하십시오. 비밀 정보는 로그에서 마스킹되며 빌드 결과물에는 절대 포함되지 않습니다.

Next.js와 Vite는 여러 .env 파일을 지원합니다. .env(모든 환경), .env.local(로컬 재정의, Git에서 무시됨), .env.development, .env.production을 사용할 수 있습니다. 로컬 파일은 공유 파일의 값을 재정의하므로 다른 환경에 영향을 주지 않고 개발자별 구성을 사용할 수 있습니다.

빌드한 후 JavaScript 번들에서 실수로 노출된 비밀 정보를 감사하십시오. grep -r "password|secret|api_key" dist/를 실행하거나, 빌드된 파일에 strings 분석과 같은 전용 도구를 사용할 수 있습니다. 실수로 포함된 일부 비밀 정보는 UUID, base64 문자열 또는 sk_live_ 같은 키 접두사처럼 형식만으로도 쉽게 식별할 수 있습니다.

각 환경과 서비스는 필요한 비밀 정보에만 접근할 수 있어야 합니다. React 클라이언트에는 비밀 정보가 전혀 필요하지 않으며 공개 식별자만 받아야 합니다. BFF 서버에도 호출하는 API에 필요한 비밀 정보만 있어야 합니다. 개발 환경에서는 권한과 지출 한도가 제한된 비프로덕션 API 키를 사용해야 합니다.

Vite는 VITE_를, Next.js는 NEXT_PUBLIC_를 사용하여 변수를 브라우저 번들에 노출합니다. 다른 모든 변수는 서버 측에서만 사용할 수 있습니다. 데이터베이스 비밀번호, API 비밀 키 또는 JWT 서명 비밀을 클라이언트 코드에 절대 포함하지 마십시오. BFF 패턴을 사용하여 민감한 API 호출을 프록시하십시오. 프로덕션 비밀 정보 관리에는 dotenv-vault, AWS Parameter Store 또는 GitHub Secrets를 사용하십시오. 실수로 노출된 비밀 정보가 있는지 빌드된 번들을 감사하십시오.