빌드와 배포

이 장에서는 Vue 프로젝트를 정적 파일로 빌드해 배포하는 방법과, Nuxt 프로젝트를 Nitro 프리셋에 맞춰 Node.js 서버나 정적 사이트로 배포하는 방법을 다룹니다.

Vue 프로젝트: vite build

create-vue 프로젝트의 npm run build는 Vite로 프로덕션 빌드를 만듭니다. TypeScript 프로젝트에서는 타입 검사(vue-tsc)도 함께 실행합니다. 결과는 dist/ 폴더에 HTML, 해시가 붙은 JS·CSS 파일로 나옵니다.

npm run build      # dist/ 생성
npm run preview    # 빌드 결과를 로컬에서 확인

dist/는 정적 파일뿐이므로 Nginx, 객체 스토리지, CDN, 정적 호스팅 서비스 어디에나 올릴 수 있습니다. 앱을 하위 경로(예: /app/)에서 서비스한다면 vite.config.ts에 base: "/app/"을 지정합니다. 빌드할 때 VITE_로 시작하는 환경 변수가 코드에 그대로 박히므로 비밀 값은 넣지 않습니다.

SPA 라우팅과 서버 설정

Vue Router의 createWebHistory를 쓰면 /about 같은 주소로 바로 접속하거나 새로 고칠 때 서버가 그 경로의 파일을 찾지 못해 404를 냅니다. 모르는 경로는 index.html을 돌려주도록 서버를 설정합니다.

server {
  listen 80;
  root /usr/share/nginx/html;

  location / {
    try_files $uri $uri/ /index.html;
  }

  location /assets/ {
    add_header Cache-Control "public, max-age=31536000, immutable";
  }
}

assets/의 파일은 이름에 내용 해시가 들어 있으므로 오래 캐시해도 안전합니다. 반면 index.html은 캐시를 짧게 두어 새 배포가 바로 반영되게 합니다.

Nuxt 프로젝트: nuxi build와 Nitro

Nuxt는 서버 엔진 Nitro로 빌드합니다. npm run build(nuxi build)를 실행하면 .output/ 폴더에 서버 코드와 정적 자원이 함께 만들어지고, 기본 프리셋인 node-server라면 Node.js로 바로 실행할 수 있습니다.

npm run build
node .output/server/index.mjs

# 포트와 런타임 설정은 환경 변수로
PORT=8080 NUXT_API_SECRET=change-me node .output/server/index.mjs

.output/는 필요한 의존성을 이미 담고 있으므로 서버에 node_modules를 따로 설치할 필요가 없습니다.

프리셋 고르기

Nitro는 같은 앱을 여러 배포 대상에 맞춰 빌드합니다. 대상은 nuxt.config.ts의 nitro.preset이나 NITRO_PRESET 환경 변수로 정합니다. Vercel, Netlify, Cloudflare 같은 플랫폼에서는 빌드 환경을 감지해 알맞은 프리셋이 자동으로 선택되는 경우가 많습니다.

export default defineNuxtConfig({
  nitro: { preset: "node-server" },
  routeRules: {
    "/": { prerender: true },          // 빌드할 때 HTML 생성
    "/blog/**": { swr: 3600 },         // 캐시 후 백그라운드 갱신
    "/admin/**": { ssr: false },       // 클라이언트에서만 렌더링
  },
});

routeRules로 경로마다 렌더링 방식을 섞을 수 있다는 점이 Nuxt의 장점입니다.

정적 사이트로 배포하기

서버 없이 정적 호스팅에 올리려면 nuxi generate를 씁니다. 링크를 따라가며 페이지를 미리 렌더링해 .output/public/에 HTML을 만듭니다. 이 방식에서는 server/api가 배포되지 않으므로, 빌드할 때 필요한 데이터만 쓰거나 외부 API를 호출해야 합니다.

npx nuxi generate
# .output/public/ 을 정적 호스팅에 업로드

Docker로 Nuxt 서버 배포하기

Node.js 서버로 운영할 때는 빌드 단계와 실행 단계를 나눈 Docker 이미지가 깔끔합니다.

FROM node:lts-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:lts-alpine
WORKDIR /app
COPY --from=build /app/.output ./.output
ENV NODE_ENV=production PORT=3000
EXPOSE 3000
CMD ["node", ".output/server/index.mjs"]

정리

• Vue 프로젝트는 npm run build로 dist/를 만들어 정적 호스팅에 올리고, SPA 경로는 index.html로 돌려줍니다.
• Nuxt는 nuxi build로 .output/을 만들며, node-server 프리셋이면 node .output/server/index.mjs로 실행합니다.
• 배포 대상은 Nitro 프리셋으로, 경로별 렌더링은 routeRules로 정합니다.
• 서버 없이 배포하려면 nuxi generate로 정적 사이트를 만듭니다.

공식 문서: Vue 프로덕션 배포, Vite 정적 사이트 배포, Nuxt 배포, Nitro 배포