[Nuxt3] 환경 변수 관리

 

runtimeConfig

---

 

Nuxt 3는 runtimeConfig API를 통해 서버 전용과 클라이언트 공개용 환경 변수를 분리해서 관리할 수 있습니다.

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // (1) 서버에서만 사용되는 키 (민감 정보)
    authCookieName: '__user',
    jwtSecretKey: 'supersecretkey',

    // (2) public 하위에 정의된 키는 클라이언트에도 노출됨
    public: {
      clientConfigValue: 'test',
    },
  },
})

 

.env 파일을 통한 값 오버라이드

• Nuxt 3는 프로젝트 루트(최상단 경로)에 .env 파일이 존재하면, 별도의 dotenv 라이브러리 없이 자동으로 로딩합니다.
• NUXT_ 접두사가 붙은 환경 변수를 nuxt.config.ts의 runtimeConfig와 연결하여 오버라이드합니다.
• SSR 서버는 Docker 컨테이너 등에서 기동할 때 받은 환경 변수를 process.env로 읽어옵니다.
• 정적으로 빌드(Static/SSG) 하는 경우, 빌드 시점의 .env나 NUXT_ 변수가 최종 HTML/JS에 임베드되어 배포됩니다.
• 이때는 런타임과 무관하게, 이미 빌드된 소스에 값이 박혀 있기 때문에, 실행 중에 변수만 교체해도 브라우저 측에 전달되지 않습니다.

# .env
NUXT_AUTH_COOKIE_NAME=__user_
NUXT_JWT_SECRET_KEY=supersecretkey_
NUXT_PUBLIC_CLIENT_CONFIG_VALUE=test_

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    authCookieName: '__user',       // 최종적으로 '__user_' 로 오버라이드
    jwtSecretKey: 'supersecretkey', // 최종적으로 'supersecretkey_'
    public: {
      clientConfigValue: 'test',    // 최종적으로 'test_'
    },
  },
})

 

app.config.ts

---

 

app.config.ts는 루트 디렉토리에 위치하며, 빌드 시점에 확정할 수 있는 공개 변수들을 정의하는 데 사용됩니다. Nuxt 3는 app.config.ts를 내부적으로 번들에 포함시켜 클라이언트와 서버 모두에서 접근할 수 있습니다.

// app.config.ts
export default defineAppConfig({
  title: 'Hello Nuxt',
  theme: {
    dark: true,
    colors: {
      primary: '#ff0000'
    }
  }
})

• app.config.ts에 정의된 값은 런타임이 아니라 빌드 시점에 결정됩니다. 즉, 환경 변수를 통해 재정의가 불가능하며, 빌드 후에는 고정됩니다.
• 클라이언트로도 번들되므로, 민감한 API 키나 비밀번호처럼 비공개가 필요한 정보는 넣으면 안 됩니다.
• 테마 설정, 사이트 타이틀, 공용 색상 팔레트 등 민감하지 않은 정보를 공통으로 관리.

사용 방법

app.config.ts에서 정의된 정보는 useAppConfig() 컴포저블로 어느 컴포넌트에서든 접근할 수 있습니다. appConfig.title 값을 불러와서 템플릿이나 로직에서 활용 가능합니다.

<!-- pages/index.vue -->
<template>
  <div>
    <h1>{{ appConfig.title }}</h1>
  </div>
</template>

<script setup lang="ts">
const appConfig = useAppConfig()
</script>

 

runtimeConfig vs. app.config.ts

---

 

Nuxt 3에서 애플리케이션의 변수를 정의하는 주요 방법은 크게 두 가지입니다. 런타임에 환경 변수로 바꿔야 하는 값은 runtimeConfig를, 빌드 시점에 고정되는 사이트 설정은 app.config.ts를 사용하는 것이 권장됩니다.

1. runtimeConfig
   • 서버 측에서만 사용 가능한 민감 정보(runtimeConfig 최상위)
   • 클라이언트에도 노출 가능한 공개 정보(runtimeConfig.public)
   • .env 파일을 통해 환경 변수로 재정의 가능
   • SSR 시점에 값이 결정되며, 여러 요청에서 동일 값을 공유 (요청당 별도 설정 가능 X)
2. app.config.ts
   • 빌드 시점에 고정되는 공개 변수
   • 환경 변수로 재정의 불가
   • 테마 변환, 사이트 제목, 프로젝트에 민감하지 않은 전역 설정을 정의할 때 유용
   • HMR(Hot Module Replacement) 등으로 개발 환경에서 빠르게 변경 내용을 확인 가능

 

기능	runtimeConfig	app.config
클라이언트 측	Hydrated (서버 생성)	Bundled (직접 포함)
환경 변수	✅ (가능)	❌ (불가)
반응형	✅ (가능)	✅ (가능)
요청당 구성(Request-scoped)	❌ (아님)	✅ (컴파일 시, 단일)
HMR (핫 모듈 교체)	❌ (X)	✅ (O)
민감 정보 저장	✅ (서버 전용 가능)	❌ (공개)

외부 구성 파일 사용

---

 

Nuxt는 단일 진입점인 nuxt.config.ts를 구성의 싱글 소스로 삼는 것을 권장합니다. 따라서 Nitro, Vite, Webpack 등 다른 툴들이 별도의 설정 파일을 사용하는 경우도 nuxt.config.ts 내에서 관리하도록 장려합니다.

 

도구	기본 구성 파일	Nuxt에서의 설정 키
Nitro	nitro.config.ts	nuxt.config 내 nitro
PostCSS	postcss.config.js	nuxt.config 내 postcss
Vite	vite.config.ts	nuxt.config 내 vite
webpack	webpack.config.ts	nuxt.config 내 webpack

그 외 일반적인 구성 파일

• tsconfig.json
• .eslintrc.js
• .prettierrc
• .stylelintrc
• tailwind.config.js
• vitest.config.ts

이러한 파일들은 프로젝트 특성상 대부분 Nuxt 컨피그와 별도로 유지하되, 필요한 경우에 한해 Nuxt에 연동하거나 scripts를 통해 실행·검증하는 식으로 운영합니다.