Ch 01. 환경별 설정 분리 (.env, runtimeConfig)

개발할 때 쓰는 데이터베이스 주소와 실제 서비스에서 쓰는 주소가 같으면 큰일입니다. 개발자가 테스트하다가 실서비스 데이터를 날릴 수도 있고, JWT 비밀키가 "test-secret" 그대로 운영에 올라가면 보안 사고로 이어집니다. 환경별 설정 분리는 선택이 아니라 필수입니다.

.env 파일 우선순위

Nuxt는 다음 순서로 .env 파일을 읽습니다. 나중에 읽은 값이 앞의 값을 덮어씁니다.

.env            → 기본값 (모든 환경)
.env.local      → 로컬 개발자 개인 설정 (git 제외)
.env.development → 개발 환경 전용
.env.production  → 운영 환경 전용

.env.local은 반드시 .gitignore에 추가해야 합니다. 개인 API 키나 로컬 DB 접속 정보를 여기에 보관합니다.

runtimeConfig와 NUXT_ 접두사

nuxt.config.ts에서 runtimeConfig를 정의하면, NUXT_ 접두사가 붙은 환경변수가 자동으로 매핑됩니다.

// nuxt.config.tsexport default defineNuxtConfig({  runtimeConfig: {    jwtSecret: 'dev-secret',          // NUXT_JWT_SECRET으로 덮어씀    databaseUrl: '',                   // NUXT_DATABASE_URL로 덮어씀    public: {      appName: '내 블로그'             // NUXT_PUBLIC_APP_NAME으로 덮어씀    }  }})

public 안에 있는 값은 클라이언트 브라우저에도 노출됩니다. 비밀 키는 절대 public 안에 넣지 않습니다.

실전 .env.production 예시

DATABASE_URL="postgresql://user:pass@db:5432/blog"
NUXT_JWT_SECRET="production-secret-key"
NUXT_PUBLIC_APP_NAME="내 블로그"

배포 환경에서 환경변수 주입

Vercel 대시보드. Project Settings > Environment Variables 메뉴에서 키와 값을 입력합니다. 재배포 시 자동으로 반영됩니다.

Docker -e 옵션. docker compose.yml의 environment 섹션에 직접 기입하거나, 호스트의 .env 파일을 env_file로 주입합니다.

services:  app:    env_file:      - .env.production

서버 코드에서는 useRuntimeConfig()로 값을 읽습니다.

// server/api/auth/login.post.tsconst config = useRuntimeConfig()const secret = config.jwtSecret   // 서버 전용

로컬 개발 시에는 .env.local을 만들어 개인 설정을 기입하고 git에 올리지 않습니다. 이것만 지켜도 많은 보안 사고를 예방할 수 있습니다.