close
프로필 배경
프로필 로고

테크 삽질 연구소

실무개발/Front · 2026. 5. 21. fullscreen 넓게보기

Nuxt4 설치부터 실제 배포까지 완벽 정리

Nuxt4 설치 방법부터 프로젝트 생성, 개발 서버 실행, 빌드, 정적 배포, Node 서버 배포, Docker 배포까지 실무 기준으로 정리합니다.

 

 

Nuxt4 설치부터 실제 배포까지 완벽 정리

Nuxt4 설치와 배포 방법을 처음부터 끝까지 정리합니다. 이 글에서는 Nuxt4 프로젝트 생성, 개발 서버 실행, 기본 페이지 작성, 환경 변수 설정, 프로덕션 빌드, 정적 배포, Node 서버 배포, Docker 배포까지 실제 운영 환경에서 필요한 흐름을 기준으로 설명합니다.

Nuxt 공식 문서 기준으로 Nuxt4는 Node.js 22.x 이상을 요구하며, Nuxt 애플리케이션은 Node 서버, 정적 호스팅, 서버리스, 엣지 환경으로 배포할 수 있습니다.

Nuxt4란?

Nuxt4는 Vue.js 기반의 풀스택 웹 프레임워크입니다. Vue만 사용할 때보다 라우팅, 서버 사이드 렌더링, 정적 사이트 생성, API 서버, 자동 import, SEO 설정 등을 더 쉽게 구성할 수 있습니다.

Nuxt4는 다음과 같은 프로젝트에 적합합니다.

용도설명
블로그 SEO가 중요한 콘텐츠 사이트
회사 홈페이지 정적 페이지 + 일부 동적 기능
관리자 페이지 Vue 기반 SPA
커머스 SSR 또는 하이브리드 렌더링
풀스택 웹서비스 Nuxt 서버 API 활용

Nuxt4 설치 전 준비 사항

Nuxt4를 설치하기 전에 Node.js 버전을 확인합니다.

 
node -v
 

Nuxt4 공식 문서 기준으로 Node.js 22.x 이상이 필요합니다.

패키지 매니저는 npm, pnpm, yarn, bun 중 하나를 사용할 수 있습니다. 실무에서는 속도와 의존성 관리 측면에서 pnpm을 많이 사용합니다.

 
npm install -g pnpm
 

버전 확인:

 
pnpm -v
 

Nuxt4 프로젝트 생성하기

Nuxt4 프로젝트는 nuxi 명령어로 생성합니다.

 
pnpm dlx nuxi@latest init nuxt4-app
 

프로젝트 폴더로 이동합니다.

 
cd nuxt4-app
 

의존성을 설치합니다.

 
pnpm install
 

개발 서버를 실행합니다.

 
pnpm dev
 

브라우저에서 아래 주소로 접속합니다.

http://localhost:3000
 

Nuxt4 기본 프로젝트 구조

Nuxt4는 기존 Nuxt3와 비교했을 때 프로젝트 구조가 더 명확해졌습니다. 공식 문서에서도 Nuxt 애플리케이션은 nuxt.config.ts를 기준으로 구성된다고 설명합니다.

대표적인 구조는 다음과 같습니다.

nuxt4-app/
├─ app/
│  ├─ app.vue
│  ├─ pages/
│  │  └─ index.vue
│  ├─ components/
│  └─ layouts/
├─ server/
│  └─ api/
├─ public/
├─ nuxt.config.ts
├─ package.json
└─ tsconfig.json
 

첫 페이지 만들기

app/pages/index.vue 파일을 생성합니다.

 
<template>
  <main>
    <h1>Nuxt4 배포 테스트</h1>
    <p>Nuxt4 설치부터 실제 배포까지 확인하는 예제입니다.</p>
  </main>
</template>
 

Nuxt는 pages 디렉터리 기반으로 자동 라우팅을 처리합니다.

예를 들어 다음 파일을 만들면:

app/pages/about.vue
 

아래 URL로 접근할 수 있습니다.

/about
 

Nuxt4 SEO 설정하기

Nuxt는 SEO 설정도 쉽게 처리할 수 있습니다.

 
<script setup lang="ts">
useHead({
  title: 'Nuxt4 설치 및 배포 가이드',
  meta: [
    {
      name: 'description',
      content: 'Nuxt4 설치부터 실제 배포까지 실무 기준으로 정리한 가이드입니다.'
    }
  ]
})
</script>

<template>
  <main>
    <h1>Nuxt4 설치 및 배포 가이드</h1>
  </main>
</template>
 

사이트 전체 기본 SEO는 nuxt.config.ts에서 설정할 수 있습니다.

 
export default defineNuxtConfig({
  app: {
    head: {
      title: 'Nuxt4 App',
      meta: [
        {
          name: 'description',
          content: 'Nuxt4로 만든 웹 애플리케이션입니다.'
        }
      ]
    }
  }
})
 

환경 변수 설정하기

실무에서는 API 주소, 서버 URL, 외부 서비스 키 등을 환경 변수로 관리합니다.

.env 파일을 생성합니다.

 
NUXT_PUBLIC_API_BASE=https://api.example.com
 

Nuxt에서 사용합니다.

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

console.log(config.public.apiBase)
</script>
 

nuxt.config.ts에 다음처럼 설정합니다.

 
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE
    }
  }
})
 

Nuxt4 빌드하기

프로덕션 배포용 빌드는 다음 명령어를 사용합니다.

 
pnpm build
 

빌드 결과는 일반적으로 .output 디렉터리에 생성됩니다.

.output/
├─ public/
└─ server/
 

Node 서버로 실행하려면 다음 명령어를 사용합니다.

 
node .output/server/index.mjs
 

Nuxt4 배포 방식 선택하기

Nuxt4는 여러 방식으로 배포할 수 있습니다. 공식 문서에서도 Nuxt 애플리케이션은 Node.js 서버, 정적 호스팅, 서버리스, 엣지 환경으로 배포할 수 있다고 안내합니다.

배포 방식명령어적합한 경우
Node 서버 배포 pnpm build SSR, API 서버 필요
정적 배포 pnpm generate 블로그, 랜딩페이지
Docker 배포 pnpm build 후 컨테이너 실행 VPS, 클라우드 서버
Vercel 배포 Git 연동 빠른 프론트 배포
Netlify 배포 Git 연동 정적 사이트 배포

정적 사이트로 배포하기

블로그, 문서 사이트, 회사 소개 페이지처럼 서버 API가 필요 없는 경우 정적 배포가 편합니다.

 
pnpm generate
 

Nuxt 공식 문서에 따르면 nuxt generate 또는 nuxt build --prerender를 사용하면 각 페이지가 정적 HTML 파일로 렌더링됩니다. 다만 정적 배포에서는 서버 엔드포인트가 포함되지 않으므로 서버 기능이 필요하면 nuxt build를 사용해야 합니다.

정적 빌드 결과물은 보통 다음 위치에 생성됩니다.

.output/public
 

이 폴더를 정적 호스팅 서버에 업로드하면 됩니다.

예를 들어 Nginx 정적 서버에 배포한다면:

 
scp -r .output/public/* user@your-server:/var/www/nuxt4-app
 

Nginx 설정 예시는 다음과 같습니다.

 
server {
    listen 80;
    server_name example.com;

    root /var/www/nuxt4-app;
    index index.html;

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

Nginx 재시작:

 
sudo nginx -t
sudo systemctl reload nginx
 

Node 서버로 Nuxt4 배포하기

SSR이 필요한 경우 Node 서버 방식으로 배포합니다.

서버에서 프로젝트를 클론합니다.

 
git clone https://github.com/your-name/nuxt4-app.git
cd nuxt4-app
 

의존성을 설치합니다.

 
pnpm install
 

빌드합니다.

 
pnpm build
 

실행합니다.

 
node .output/server/index.mjs
 

운영 환경에서는 PM2를 사용하는 것이 일반적입니다.

 
npm install -g pm2
 

Nuxt4 앱 실행:

 
pm2 start .output/server/index.mjs --name nuxt4-app
 

서버 재부팅 후 자동 실행:

 
pm2 save
pm2 startup
 

PM2 ecosystem 파일로 관리하기

ecosystem.config.cjs 파일을 생성합니다.

 
module.exports = {
  apps: [
    {
      name: 'nuxt4-app',
      script: '.output/server/index.mjs',
      env: {
        NODE_ENV: 'production',
        PORT: 3000,
        NUXT_PUBLIC_API_BASE: 'https://api.example.com'
      }
    }
  ]
}
 

실행합니다.

 
pm2 start ecosystem.config.cjs
 

로그 확인:

 
pm2 logs nuxt4-app
 

재시작:

 
pm2 restart nuxt4-app
 

Nginx 리버스 프록시 설정

Node 서버는 보통 3000번 포트에서 실행하고, 외부 접속은 Nginx가 80 또는 443 포트로 받아서 Nuxt 앱으로 전달합니다.

 
server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
 

설정 확인:

 
sudo nginx -t
 

적용:

 
sudo systemctl reload nginx
 

HTTPS 적용하기

Let’s Encrypt를 사용하면 무료 SSL 인증서를 적용할 수 있습니다.

 
sudo apt install certbot python3-certbot-nginx
 

인증서 발급:

 
sudo certbot --nginx -d example.com
 

자동 갱신 확인:

 
sudo certbot renew --dry-run
 

Docker로 Nuxt4 배포하기

Docker를 사용하면 서버 환경 차이로 인한 문제를 줄일 수 있습니다.

Dockerfile을 생성합니다.

 
FROM node:22-alpine AS builder

WORKDIR /app

COPY package.json pnpm-lock.yaml ./

RUN corepack enable
RUN pnpm install --frozen-lockfile

COPY . .

RUN pnpm build

FROM node:22-alpine AS runner

WORKDIR /app

ENV NODE_ENV=production
ENV PORT=3000

COPY --from=builder /app/.output ./.output

EXPOSE 3000

CMD ["node", ".output/server/index.mjs"]
 

이미지 빌드:

 
docker build -t nuxt4-app .
 

컨테이너 실행:

 
docker run -d \
  --name nuxt4-app \
  -p 3000:3000 \
  --restart unless-stopped \
  nuxt4-app
 

로그 확인:

 
docker logs -f nuxt4-app
 

Docker Compose로 배포하기

docker-compose.yml 파일을 생성합니다.

 
services:
  nuxt4-app:
    build: .
    container_name: nuxt4-app
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      PORT: 3000
      NUXT_PUBLIC_API_BASE: https://api.example.com
    restart: unless-stopped
 

실행:

 
docker compose up -d --build
 

중지:

 
docker compose down
 

GitHub Actions로 자동 배포하기

서버에 SSH로 접속해 자동 배포하는 예시입니다.

.github/workflows/deploy.yml

 
name: Deploy Nuxt4 App

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Deploy to server
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          script: |
            cd /var/www/nuxt4-app
            git pull origin main
            corepack enable
            pnpm install --frozen-lockfile
            pnpm build
            pm2 restart nuxt4-app || pm2 start .output/server/index.mjs --name nuxt4-app
 

GitHub Secrets에는 다음 값을 등록합니다.

이름설명
SERVER_HOST 서버 IP
SERVER_USER SSH 사용자
SERVER_SSH_KEY 개인키
SERVER_PORT SSH 포트, 필요 시

Nuxt4 배포 시 자주 발생하는 문제

1. Node 버전 오류

Nuxt4는 Node.js 22.x 이상이 필요합니다. 서버 Node 버전이 낮으면 빌드나 실행 중 오류가 발생할 수 있습니다.

 
node -v
 

해결 방법:

 
nvm install 22
nvm use 22
 

2. 서버에서는 되는데 새로고침 시 404 발생

정적 배포에서 SPA처럼 동작하는 페이지가 새로고침 시 404가 나는 경우가 있습니다.

Nginx 설정에 다음이 필요합니다.

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

3. 환경 변수가 반영되지 않음

Nuxt는 빌드 시점과 런타임 시점의 환경 변수 차이를 이해해야 합니다.

특히 NUXT_PUBLIC_으로 시작하는 값은 클라이언트에서도 접근할 수 있습니다.

 
NUXT_PUBLIC_API_BASE=https://api.example.com
 

4. 서버 API가 필요한데 정적 배포를 사용함

pnpm generate로 정적 배포를 하면 서버 엔드포인트가 포함되지 않습니다. 서버 API가 필요하면 pnpm build 후 Node 서버로 배포해야 합니다.

실무 기준 추천 배포 방식

개인 블로그나 문서 사이트라면 정적 배포가 가장 단순합니다.

 
pnpm generate
 

서비스형 웹사이트, 로그인, API, SSR이 필요하다면 Node 서버 배포가 적합합니다.

 
pnpm build
node .output/server/index.mjs
 

운영 서버를 직접 관리한다면 Docker 배포가 안정적입니다.

 
docker compose up -d --build
 

FAQ

Q1. Nuxt4는 Nuxt3와 많이 다른가요?

기본 개발 방식은 비슷하지만 Nuxt4는 프로젝트 구조, 타입 안정성, 데이터 fetching 개선 등 개발 경험을 개선한 버전입니다. Nuxt 공식 블로그에서도 Nuxt4를 개발 경험과 안정성 중심의 주요 릴리스로 설명합니다.

Q2. Nuxt4는 무조건 SSR로 배포해야 하나요?

아닙니다. Nuxt4는 SSR, 정적 사이트, 서버리스, 엣지 환경 등 다양한 배포 방식을 지원합니다.

Q3. 블로그는 어떤 방식으로 배포하는 것이 좋나요?

콘텐츠 중심 블로그라면 정적 배포가 좋습니다. 속도가 빠르고 서버 관리 부담이 적습니다.

Q4. 로그인 기능이 있는 서비스도 정적 배포가 가능한가요?

가능은 하지만 서버 API, 인증 처리, SSR이 필요하다면 Node 서버 배포가 더 적합합니다.

Q5. Nuxt4 배포 시 가장 먼저 확인할 것은 무엇인가요?

Node.js 버전, 환경 변수, 빌드 명령어, 실행 포트, Nginx 프록시 설정을 먼저 확인하는 것이 좋습니다.

마무리

Nuxt4 설치부터 실제 배포까지의 핵심 흐름은 간단합니다. 먼저 nuxi로 프로젝트를 생성하고, pnpm dev로 개발 서버를 실행한 뒤, 배포 방식에 따라 pnpm build 또는 pnpm generate를 선택하면 됩니다. 서버 API와 SSR이 필요하면 Node 서버 배포를 선택하고, 단순 블로그나 랜딩페이지라면 정적 배포를 선택하는 것이 실무적으로 가장 효율적입니다.

5. 추천 태그

Nuxt4, Nuxt4 설치, Nuxt4 배포, Nuxt 배포, Nuxt SSR, Nuxt Static, Nuxt Docker, Vue 프레임워크, 프론트엔드 배포, Node 서버 배포, PM2 배포, Nginx 리버스 프록시, Docker Compose, GitHub Actions 배포

'실무개발 > Front' 카테고리의 다른 글

Nuxt와 Codex로 만든 알뜰폰 요금제 비교 서비스 개발기  (0) 2026.06.02
실무개발/Front 관련 글
더 보기

티스토리툴바