배포

개발이 끝나면 앱을 실제 서버나 호스팅에 올려야 합니다. Nuxt는 Nitro 덕분에 하나의 코드로 여러 환경(서버·정적·서버리스) 에 배포할 수 있습니다. 이번 레슨에서는 build 와 generate 의 차이, .output 구조, 배포 프리셋, 그리고 환경 변수 관리를 다룹니다.

학습 목표

• nuxt build 와 nuxt generate 의 차이를 안다.
• 빌드 결과물인 .output 구조를 이해한다.
• 배포 대상에 맞는 프리셋을 고른다.
• runtimeConfig 로 환경 변수를 안전하게 다룬다.

build vs generate

명령	결과물	적합한 경우
nuxt build	서버 + 클라이언트 번들 (.output)	SSR/동적 콘텐츠, 서버 실행
nuxt generate	정적 HTML (.output/public)	SSG, 정적 호스팅(CDN)

# 서버 배포용 (SSR)
npx nuxi build

# 정적 사이트 (SSG)
npx nuxi generate

💡 TIP — generate 는 사실 build 에 prerender 를 켠 것과 같습니다. 모든 경로를 미리 HTML로 만들어 정적 폴더를 생성합니다.

.output 구조

nuxt build 의 결과는 .output/ 에 모입니다.

.output/
├── public/         # 정적 에셋 (JS·CSS·이미지)
├── server/         # Nitro 서버 번들
│   └── index.mjs   # 서버 진입점
└── nitro.json      # 빌드 메타데이터

서버를 직접 실행하려면 진입점을 노드로 띄웁니다.

node .output/server/index.mjs
# 기본적으로 http://localhost:3000 에서 동작

배포 프리셋

Nitro는 배포 대상에 맞는 프리셋 을 골라 출력 형태를 바꿉니다. 대부분 환경은 자동 감지되지만, 직접 지정할 수도 있습니다.

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'node-server', // 기본 노드 서버
  },
});

또는 환경 변수로 빌드 시 지정합니다.

NITRO_PRESET=node-server npx nuxi build

프리셋	배포 대상
node-server	일반 Node.js 서버(직접 호스팅)
static	정적 호스팅(generate 와 함께)
vercel / netlify	서버리스 플랫폼(보통 자동 감지)
cloudflare	엣지 워커

⚠️ 주의 — 서버리스·엣지 환경은 파일 시스템·장기 실행 같은 제약이 있습니다. DB 연결 등은 각 플랫폼 가이드를 확인하세요.

환경 변수와 runtimeConfig

API 키 같은 민감한 값은 코드에 박지 말고 runtimeConfig 로 다룹니다. 최상위는 서버 전용, public 아래는 클라이언트에도 노출 됩니다.

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '',          // 서버 전용 (브라우저에 노출 안 됨)
    public: {
      apiBase: '/api',      // 클라이언트에서도 접근 가능
    },
  },
});

값은 .env 의 환경 변수로 덮어씁니다. 이름 규칙은 NUXT_ 접두사입니다.

# .env
NUXT_API_SECRET=super-secret-key
NUXT_PUBLIC_API_BASE=https://api.example.com

읽을 때는 useRuntimeConfig() 를 씁니다.

// 서버 라우트 (server/api/...)
export default defineEventHandler(() => {
  const config = useRuntimeConfig();
  const secret = config.apiSecret; // 서버에서만 안전하게 접근
  // ...
});

<script setup>
// 컴포넌트 — public 값만 접근
const config = useRuntimeConfig();
const base = config.public.apiBase;
</script>

⚠️ 주의 — runtimeConfig 최상위 값(apiSecret)을 클라이언트 코드에서 읽으면 비어 있습니다. 브라우저에 필요한 값은 반드시 public 아래에 두세요.

배포 흐름 정리

1. 코드 작성·테스트
2. nuxt build (또는 generate)
3. .output 산출물 확인
4. 환경 변수(.env / 플랫폼 설정) 주입
5. node .output/server/index.mjs  또는  플랫폼에 업로드

요약

• nuxt build 는 서버 번들을, nuxt generate 는 정적 HTML을 만듭니다.
• 결과물은 .output/(서버는 server/index.mjs, 정적은 public/)에 모입니다.
• nitro.preset 으로 노드·정적·서버리스 등 배포 대상을 정합니다.
• 비밀 값은 runtimeConfig(서버 전용)와 public(클라이언트 노출)으로 구분해 다룹니다.

연습문제

1. nuxi build 와 nuxi generate 를 각각 실행하고 .output 구조가 어떻게 다른지 비교해 보세요.
2. node .output/server/index.mjs 로 빌드된 서버를 직접 띄워 보세요.
3. runtimeConfig 에 apiSecret(서버)과 public.apiBase(클라이언트)를 정의하고 각각 읽어 보세요.
4. .env 에 NUXT_PUBLIC_API_BASE 를 설정해 코드 수정 없이 값을 바꿔 보세요.

힌트 — 정적 산출물은 public/, 비밀 값은 public 바깥, 환경 변수는 NUXT_ 접두사라는 점을 떠올리세요.