앱의 나머지 부분에 설정과 환경 변수를 노출하려면, nuxt.config 파일에서 runtimeConfig 옵션을 사용해 런타임 설정을 정의해야 합니다.
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)
$config.public으로 접근할 수 있습니다.런타임 설정은 Nitro로 전달되기 전에 직렬화됩니다. 이는 함수, Set, Map 등과 같이 직렬화 후 역직렬화가 불가능한 값들은 nuxt.config에 설정하면 안 된다는 의미입니다.
nuxt.config에서 애플리케이션으로 직렬화 불가능한 객체나 함수를 전달하는 대신, 이 코드를 Nuxt 또는 Nitro 플러그인이나 미들웨어에 배치할 수 있습니다.
설정을 제공하는 가장 일반적인 방법은 환경 변수를 사용하는 것입니다.
.env 파일을 읽는 기능을 내장하고 있습니다. 하지만 빌드된 서버를 실행할 때는 .env 파일이 읽히지 않습니다.런타임 설정 값은 런타임에 일치하는 환경 변수로 자동 치환됩니다.
두 가지 핵심 요구 사항이 있습니다:
nuxt.config에 정의되어 있어야 합니다. 이는 임의의 환경 변수가 애플리케이션 코드에 노출되지 않도록 보장합니다.NUXT_로 시작하고, 키와 대소문자 변경을 _로 구분하는 대문자 환경 변수여야 합니다.runtimeConfig 값의 기본값을 다른 이름의 환경 변수로 설정하는 것(예: myVar를 process.env.OTHER_VARIABLE로 설정)은 빌드 타임에만 동작하며 런타임에는 깨집니다.
runtimeConfig 객체의 구조와 일치하는 환경 변수를 사용하는 것이 좋습니다.NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://nuxtjs.org
export default defineNuxtConfig({
runtimeConfig: {
apiSecret: '', // NUXT_API_SECRET 환경 변수로 오버라이드될 수 있음
public: {
apiBase: '', // NUXT_PUBLIC_API_BASE 환경 변수로 오버라이드될 수 있음
},
},
})
Nuxt 앱의 Vue 부분에서 런타임 설정에 접근하려면 useRuntimeConfig()를 호출해야 합니다.
runtimeConfig.public과 runtimeConfig.app(Nuxt 내부에서 사용됨)의 키만 사용할 수 있으며, 이 객체는 쓰기 가능하고 반응형입니다.<script setup lang="ts">
const config = useRuntimeConfig()
console.log('Runtime config:', config)
if (import.meta.server) {
console.log('API secret:', config.apiSecret)
}
</script>
<template>
<div>
<div>개발자 콘솔을 확인하세요!</div>
</div>
</template>
useState에 전달하여 클라이언트 사이드에 노출하지 않도록 주의하세요.(커스텀) 플러그인 내에서 런타임 설정을 사용하려면, defineNuxtPlugin 함수 내부에서 useRuntimeConfig()를 사용할 수 있습니다.
export default defineNuxtPlugin((nuxtApp) => {
const config = useRuntimeConfig()
console.log('API base URL:', config.public.apiBase)
})
useRuntimeConfig를 사용해 서버 라우트 내에서도 런타임 설정에 접근할 수 있습니다.
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를 사용해 타입스크립트 인터페이스를 자동으로 생성하려고 시도합니다.
하지만 런타임 설정을 수동으로 타입 지정하는 것도 가능합니다:
declare module 'nuxt/schema' {
interface RuntimeConfig {
apiSecret: string
}
interface PublicRuntimeConfig {
apiBase: string
}
}
// 타입을 보강할 때는 항상 무언가를 import/export 하는 것이 중요합니다
export {}
nuxt/schema는 최종 사용자가 자신의 프로젝트에서 Nuxt가 사용하는 스키마 버전에 접근할 수 있도록 편의를 위해 제공됩니다. 모듈 작성자는 대신 @nuxt/schema를 보강해야 합니다.