Files

gil 5070852ab8 docs: update wiki with new pages and content

- Removed `.claude/` from .gitignore
- Updated index.md to reflect the addition of 7 new wiki pages, increasing total pages to 11
- Added detailed summaries for new pages including rendering modes, lifecycle, routing, data fetching, state management, auto imports, layers, performance, and runtime config
- Created nuxt-runtime-config.md to document runtime configuration and environment variable handling
- Updated log.md to include entries for newly created wiki pages

2026-05-13 00:34:38 +09:00

3.5 KiB

Raw Blame History

Nuxt Runtime Config & 환경 변수

카테고리: 성능 & 배포 최종 수정: 2026-05-13 관련: nuxt-lifecycle, nuxt-layers

요약

runtimeConfig는 빌드 시 고정되지 않고 런타임에 환경 변수로 덮어쓸 수 있는 설정이다. runtimeConfig.public은 클라이언트에도 노출되고, 그 외는 서버 전용.

기본 설정

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 서버 전용 (클라이언트 노출 안됨)
    apiSecret: '123',
    dbPassword: '',

    // public: 서버·클라이언트 모두 접근 가능
    public: {
      apiBase: '/api',
      appVersion: '1.0.0',
    },
  },
})

환경 변수로 오버라이드

네이밍 규칙

NUXT_ 접두사 + 대문자 + _로 구분:

# .env
NUXT_API_SECRET=prod-secret-token
NUXT_PUBLIC_API_BASE=https://api.example.com
NUXT_DB_PASSWORD=secret123

// 런타임에 자동으로 오버라이드됨
runtimeConfig: {
  apiSecret: '',       // → NUXT_API_SECRET
  dbPassword: '',      // → NUXT_DB_PASSWORD
  public: {
    apiBase: '/api',   // → NUXT_PUBLIC_API_BASE
  },
}

⚠️ 주의: .env 파일은 개발·빌드·generate 시에만 읽힘. 프로덕션 서버 실행 시에는 .env 미적용. 환경 변수는 OS 또는 플랫폼에서 직접 설정해야 함.

접근 방법

Vue 컴포넌트에서

<script setup lang="ts">
const config = useRuntimeConfig()

// 클라이언트에서는 public만 접근 가능
console.log(config.public.apiBase)

// 서버에서는 전체 접근 가능
if (import.meta.server) {
  console.log(config.apiSecret)
}
</script>

⚠️ 주의: 서버 전용 키를 template에 렌더링하거나 useState에 저장하면 클라이언트에 노출됨.

플러그인에서

// app/plugins/api.ts
export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()
  // config.public.apiBase 사용
})

서버 API 라우트에서

// server/api/data.ts
export default defineEventHandler(async (event) => {
  const { apiSecret } = useRuntimeConfig(event)  // event 전달 권장
  const result = await $fetch('https://external-api.com/data', {
    headers: { Authorization: `Bearer ${apiSecret}` },
  })
  return result
})

TypeScript 타입 추가

// index.d.ts
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    apiSecret: string
    dbPassword: string
  }
  interface PublicRuntimeConfig {
    apiBase: string
    appVersion: string
  }
}
export {}

직렬화 주의사항

runtimeConfig는 Nitro로 전달 전 직렬화됨. 함수, Set, Map, 클래스 인스턴스는 설정하면 안 됨.

// ❌ 직렬화 불가
runtimeConfig: {
  myFn: () => 'hello',  // 함수 불가
}

// ✅ 플러그인에서 처리
// app/plugins/my-plugin.ts
export default defineNuxtPlugin(() => {
  const myFn = () => 'hello'
  return { provide: { myFn } }
})

`public` vs 일반 설정 비교

	`runtimeConfig`	`runtimeConfig.public`	`appConfig`
노출 대상	서버 전용	서버·클라이언트	서버·클라이언트
런타임 오버라이드	✅ (환경 변수)	✅ (환경 변수)	❌
빌드 후 변경	✅	✅	❌
용도	API 키, 시크릿	공개 API URL, 앱 버전	테마, UI 설정

참고 / 출처

reference/3.guide/6.going-further/10.runtime-config.md

3.5 KiB Raw Blame History