런타임 구성

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에 전달되기 전에 직렬화됩니다. 즉, 직렬화 및 역직렬화할 수 없는 항목(예: 함수, Sets, Maps 등)은 nuxt.config에 설정하지 않아야 합니다.

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

환경 변수

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

Nuxt CLI는 개발, 빌드 및 생성 시 .env 파일을 읽는 것을 기본적으로 지원합니다. 그러나 빌드된 서버를 실행할 때는 .env 파일이 읽히지 않습니다.

이것도 참고 guide > directory-structure > env

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

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

원하는 변수는 nuxt.config에 정의되어 있어야 합니다. 이는 임의의 환경 변수가 애플리케이션 코드에 노출되지 않도록 보장합니다.
특수하게 명명된 환경 변수만 런타임 구성 속성을 재정의할 수 있습니다. 즉, NUXT_로 시작하고 키와 대소문자 변경을 _로 구분하는 대문자 환경 변수입니다.

runtimeConfig 값의 기본값을 다르게 명명된 환경 변수로 설정하는 것(예: myVar를 process.env.OTHER_VARIABLE로 설정)은 빌드 시에만 작동하며 런타임에서는 작동하지 않습니다. runtimeConfig 객체의 구조와 일치하는 환경 변수를 사용하는 것이 좋습니다.

Alexander Lichter가 런타임 구성을 사용할 때 개발자가 저지르는 주요 실수를 보여주는 비디오를 시청하세요.

예제

.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를 확장해야 합니다.

※이 페이지는 Nuxt.js 공식 문서의 비공식 번역 페이지입니다.

공식 문서의 해당 페이지는 여기 있습니다:
https://nuxt.com/docs/3.x/guide/going-further/runtime-config