v3
Nuxt on GitHub

런타임 구성

Nuxt는 애플리케이션 내에서 구성과 비밀 정보를 노출할 수 있는 런타임 구성 API를 제공합니다.

노출하기

앱의 다른 부분에 구성과 환경 변수를 노출하려면, nuxt.config 파일에서 runtimeConfig 옵션을 사용하여 런타임 구성을 정의해야 합니다.

nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 서버 사이드에서만 사용할 수 있는 비공개 키
    apiSecret: '123',
    // public 내의 키는 클라이언트 사이드에도 노출됩니다
    public: {
      apiBase: '/api'
    }
  }
})

runtimeConfig.public에 apiBase를 추가하면, Nuxt는 이를 각 페이지 페이로드에 추가합니다. 우리는 서버와 브라우저 모두에서 apiBase에 범용적으로 접근할 수 있습니다.

const runtimeConfig = useRuntimeConfig()

console.log(runtimeConfig.apiSecret)
console.log(runtimeConfig.public.apiBase)
공개 런타임 구성은 Vue 템플릿에서 $config.public으로 접근할 수 있습니다.

직렬화

런타임 구성은 Nitro에 전달되기 전에 직렬화됩니다. 즉, 직렬화 및 역직렬화가 불가능한 것들(함수, Set, Map 등)은 nuxt.config에 설정하면 안 됩니다.

직렬화할 수 없는 객체나 함수를 nuxt.config에서 애플리케이션으로 전달하는 대신, 이 코드를 Nuxt 또는 Nitro 플러그인이나 미들웨어에 배치할 수 있습니다.

환경 변수

구성을 제공하는 가장 일반적인 방법은 환경 변수를 사용하는 것입니다.

Nuxt CLI는 개발, 빌드, 생성 시 .env 파일을 읽는 기능을 내장하고 있습니다. 하지만 빌드된 서버를 실행할 때는 .env 파일이 읽히지 않습니다.
Read more in Docs > Guide > Directory Structure > Env.

런타임 구성 값은 런타임에 일치하는 환경 변수로 자동 대체됩니다.

두 가지 주요 요구 사항이 있습니다:

  1. 원하는 변수는 반드시 nuxt.config에 정의되어 있어야 합니다. 이는 임의의 환경 변수가 애플리케이션 코드에 노출되는 것을 방지합니다.
  2. 오직 특별한 이름의 환경 변수만이 런타임 구성 속성을 덮어쓸 수 있습니다. 즉, 대문자로 시작하고 NUXT_로 시작하며, 키와 대소문자 변경을 _로 구분하는 환경 변수입니다.
runtimeConfig 값의 기본값을 다른 이름의 환경 변수 (예: myVar를 process.env.OTHER_VARIABLE로 설정)로 지정하면 빌드 타임에만 동작하고 런타임에는 동작하지 않습니다. runtimeConfig 객체의 구조와 일치하는 환경 변수를 사용하는 것이 좋습니다.
Alexander Lichter가 runtimeConfig 사용 시 개발자들이 가장 많이 하는 실수를 보여주는 영상을 시청하세요.

예시

.env
NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://nuxtjs.org
nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '', // NUXT_API_SECRET 환경 변수로 덮어쓸 수 있습니다
    public: {
      apiBase: '', // NUXT_PUBLIC_API_BASE 환경 변수로 덮어쓸 수 있습니다
    }
  },
})

읽기

Vue 앱

Nuxt 앱의 Vue 부분에서는 useRuntimeConfig()를 호출하여 런타임 구성에 접근해야 합니다.

클라이언트 사이드와 서버 사이드에서 동작이 다릅니다:
  • 클라이언트 사이드에서는 runtimeConfig.public과 Nuxt 내부적으로 사용되는 runtimeConfig.app의 키만 사용할 수 있으며, 객체는 쓰기 가능하고 반응형입니다.
  • 서버 사이드에서는 전체 런타임 구성에 접근할 수 있지만, 컨텍스트 공유를 방지하기 위해 읽기 전용입니다.
pages/index.vue
<script setup lang="ts">
const config = useRuntimeConfig()

console.log('런타임 구성:', config)
if (import.meta.server) {
  console.log('API 비밀:', config.apiSecret)
}
</script>

<template>
  <div>
    <div>개발자 콘솔을 확인하세요!</div>
  </div>
</template>
보안 주의: 런타임 구성 키를 렌더링하거나 useState에 전달하여 클라이언트 사이드에 노출하지 않도록 주의하세요.

플러그인

(커스텀) 플러그인 내에서 런타임 구성을 사용하려면, defineNuxtPlugin 함수 내부에서 useRuntimeConfig()를 사용할 수 있습니다.

plugins/config.ts
export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()

  console.log('API 기본 URL:', config.public.apiBase)
});

서버 라우트

서버 라우트 내에서도 useRuntimeConfig를 사용하여 런타임 구성에 접근할 수 있습니다.

server/api/test.ts
export default defineEventHandler(async (event) => {
  const { apiSecret } = useRuntimeConfig(event)
  const result = await $fetch('https://my.api.com/test', {
    headers: {
      Authorization: `Bearer ${apiSecret}`
    }
  })
  return result
})
useRuntimeConfig에 event를 인자로 전달하는 것은 선택 사항이지만, 서버 라우트에서 런타임에 환경 변수로 덮어쓰기를 적용받으려면 전달하는 것이 권장됩니다.

런타임 구성 타입 지정

Nuxt는 unjs/untyped를 사용하여 제공된 런타임 구성에서 타입스크립트 인터페이스를 자동으로 생성하려고 시도합니다.

하지만 런타임 구성을 수동으로 타입 지정하는 것도 가능합니다:

index.d.ts
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    apiSecret: string
  }
  interface PublicRuntimeConfig {
    apiBase: string
  }
}
// 타입을 보강할 때는 항상 무언가를 import/export 해야 합니다
export {}
nuxt/schema는 Nuxt가 프로젝트에서 사용하는 스키마 버전에 최종 사용자가 접근할 수 있도록 편의를 위해 제공됩니다. 모듈 작성자는 대신 @nuxt/schema를 보강해야 합니다.