Nuxt 3와 4에서 runtimeConfig로 환경변수 관리하기

Nuxt 2 시절에는 dotenv 패키지를 직접 불러오고 nuxt.config.js의 env에 값을 매핑하는 예제가 흔했다.
Nuxt 3와 Nuxt 4에서는 runtimeConfig를 기준으로 환경변수를 관리하는 것이 기본이다.

runtimeConfig의 역할

runtimeConfig는 이름 그대로 런타임에서 사용할 설정을 모아두는 곳이다.
서버에서만 읽을 값과 브라우저에도 노출해도 되는 값을 나누어 관리할 수 있다.

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '',
    public: {
      apiBase: '',
    },
  },
})

runtimeConfig.apiSecret은 서버에서만 사용할 값이고, runtimeConfig.public.apiBase는 클라이언트에도 노출되는 값이다.
브라우저에 전달되면 안 되는 토큰, DB 비밀번호, 내부 API key는 public 아래에 넣으면 안 된다.

.env와 NUXT_ 환경변수

로컬 개발에서는 .env 파일에 값을 둘 수 있다.

NUXT_API_SECRET=local-secret
NUXT_PUBLIC_API_BASE=http://localhost:3001

Nuxt는 runtimeConfig 키와 매칭되는 NUXT_ 환경변수를 런타임에 읽어 덮어쓴다.
중첩된 값은 _로 이어서 표현한다.

• runtimeConfig.apiSecret → NUXT_API_SECRET
• runtimeConfig.public.apiBase → NUXT_PUBLIC_API_BASE

기본값은 nuxt.config.ts에 두고, 실제 환경별 값은 배포 환경의 환경변수로 주입하는 방식이 안전하다.

서버에서 사용하기

서버 API나 Nitro server route에서는 useRuntimeConfig()로 서버 전용 값까지 읽을 수 있다.

// server/api/profile.get.ts
export default defineEventHandler(async () => {
  const config = useRuntimeConfig()

  return $fetch('/profile', {
    baseURL: config.public.apiBase,
    headers: {
      Authorization: `Bearer ${config.apiSecret}`,
    },
  })
})

서버 코드에서는 private 값과 public 값을 모두 사용할 수 있다.

클라이언트에서 사용하기

Vue 컴포넌트나 클라이언트 코드에서는 public 값만 사용한다고 생각하면 된다.

<script setup lang="ts">
const config = useRuntimeConfig()
const apiBase = config.public.apiBase
</script>

<template>
  <p>API Base URL: {{ apiBase }}</p>
</template>

public 아래에 둔 값은 클라이언트 번들 또는 payload를 통해 브라우저에 전달될 수 있다.
따라서 이름 그대로 공개 가능한 값만 넣어야 한다.

정리

Nuxt 3와 4에서는 환경변수를 직접 process.env로 흩뿌리기보다 runtimeConfig에 먼저 구조를 잡는 편이 좋다.

• 서버 전용 값은 runtimeConfig 최상위에 둔다.
• 브라우저에 공개해도 되는 값만 runtimeConfig.public에 둔다.
• 배포 환경에서는 NUXT_ 접두사의 환경변수로 값을 주입한다.
• 비밀 값은 절대 public 아래에 두지 않는다.

이렇게 하면 로컬, 스테이징, 프로덕션 환경에서 같은 코드 구조를 유지하면서 값만 안전하게 바꿀 수 있다.

참고 자료

• Nuxt docs: Runtime Config
• Nuxt docs: Environment Variables and Private Tokens