Vue 배포

Vue dist 폴더를
HTTPS로 공개하세요

Vue, Vite, Vue CLI, Nuxt 정적 결과물을 업로드하고 history mode fallback, HTTPS, 커스텀 도메인을 배포 흐름 안에서 준비하세요.

배포 절차 보기
Vue 결과물 확인
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
plugins: [vue()],
// Use a deploy-safe asset base
base: './',
build: {
outDir: 'dist'
}
})
라우트와 자산 점검 중

Vue 결과물 폴더 선택

빌드 도구마다 생성 위치가 다릅니다.

Vite 기반 Vue

npm run build
output: dist/

Vite는 기본적으로 dist에 프로덕션 빌드를 만듭니다. build.outDir이나 base를 바꿨다면 실제 결과물 폴더와 자산 URL을 확인하세요.

Vue CLI

npm run build
output: dist/

Vue CLI 정적 빌드도 보통 dist를 배포합니다. 하위 경로에서 열릴 경우 publicPath가 최종 URL 구조와 맞아야 합니다.

Nuxt 정적 결과물

nuxi generate
output: .output/public 또는 dist/

Nuxt도 정적 결과물을 만들 수 있습니다. 서버 렌더링 라우트와 server API는 런타임이 필요하므로, 이 흐름에서는 생성된 public 정적 파일만 업로드합니다.

Vue 정적 사이트 배포 방식

dist 폴더가 배포 단위입니다

Vue 프로젝트는 빌드 후 생성되는 정적 파일을 기준으로 공개합니다. 소스 파일이나 node_modules를 올리는 방식이 아닙니다.

DeployPages는 결과물 폴더를 공개 링크로 게시하고, 깔끔한 URL과 history mode 라우트가 브라우저에서 이어지도록 도와줍니다.

history mode fallback

요청 경로가 실제 정적 파일과 맞지 않으면 DeployPages가 root index.html을 제공하고 Vue Router가 브라우저에서 최종 화면을 결정합니다.

  • 새로고침해도 /projects/demo 같은 경로가 유지됩니다.
  • 공유 링크를 직접 열어도 앱이 로드됩니다.
  • 정적 파일 경로와 브라우저 라우트를 분리해 관리할 수 있습니다.

공개 전 체크리스트

Vue 배포 문제는 대부분 경로와 라우팅에서 드러납니다.

base와 publicPath

Vite는 base, Vue CLI는 publicPath를 확인합니다. 값이 틀리면 CSS, JS, 폰트, 이미지가 누락되어 보입니다.

중첩 라우트

중첩 경로를 직접 열고 새로고침합니다. 화면이 유지되면 fallback이 제대로 동작하는 것입니다.

서버 기능 분리

DeployPages는 정적 파일을 제공합니다. API route, server middleware, SSR 전용 동작은 별도 백엔드나 런타임이 필요합니다.

로컬 preview

프로덕션 빌드는 실제 미리보기 서버로 확인하세요. file://로 dist/index.html을 여는 방식은 실제 배포와 다른 문제를 만들 수 있습니다.

Vue 사이트 게시 절차

01

정적 빌드 만들기

Vite, Vue CLI, Nuxt static mode에서 프로덕션 빌드를 실행해 브라우저가 직접 읽을 수 있는 파일을 만듭니다.

02

결과물 위치 확인

대부분의 Vue/Vite 프로젝트는 dist를 만듭니다. Nuxt 정적 프로젝트는 설정에 따라 .output/public 또는 dist를 배포합니다.

프로젝트 루트가 아니라 생성된 결과물 폴더를 올리는 것이 기준입니다.

03

폴더 업로드 후 검증

결과물 폴더 전체를 업로드한 뒤 딥링크, 라우터 이동, 자산 경로를 실제 공개 링크에서 확인합니다.

Vue 배포 문제 해결

Fix 01

CSS와 JS가 404를 반환합니다

Vite base 또는 Vue CLI publicPath가 최종 URL과 맞는지 확인하고, 자산 폴더가 함께 업로드되었는지 봅니다.

Fix 02

새로고침하면 라우트가 깨집니다

history mode를 쓴다면 index.html fallback이 필요한 경로입니다. 결과물 폴더 전체를 다시 게시하고 딥링크를 테스트하세요.

Fix 03

Nuxt 페이지 일부가 동작하지 않습니다

정적 generate로 만들 수 없는 서버 의존 기능이 있는지 확인하세요. SSR이나 server API는 별도 런타임이 필요합니다.

Fix 04

로컬에서는 되는데 공개 링크에서 다릅니다

file:// 테스트 대신 preview 서버와 실제 공개 URL에서 확인하세요. 상대 경로와 base 설정 차이가 원인일 수 있습니다.

자주 묻는 질문

CSS와 JS 파일이 404가 되는 이유는 무엇인가요?

다른 base URL 기준으로 빌드되었거나 자산 폴더가 업로드되지 않았을 때 자주 발생합니다. Vite는 base, Vue CLI는 publicPath를 확인하세요.

Nuxt도 지원하나요?

정적 결과물이라면 가능합니다. 먼저 정적 사이트를 generate한 뒤 생성된 public 폴더를 업로드하세요. Nuxt server rendering이나 server API route는 이 대상에 맞지 않습니다.

hash mode와 history mode 중 무엇을 써야 하나요?

깔끔한 URL이 필요하고 host가 index.html fallback을 지원한다면 history mode가 좋습니다. hash mode는 호스팅이 단순하지만 모든 client route에 #이 남습니다.

Vue 소스 프로젝트를 올려야 하나요?

아니요. 프로덕션 결과물 폴더를 올립니다. 보통 dist입니다. 소스 프로젝트에는 직접 서비스할 필요가 없는 개발 파일과 의존성이 포함됩니다.

Pinia나 Vuex 상태가 새로고침 후에도 유지되나요?

자동으로 유지되지는 않습니다. 브라우저 새로고침은 메모리 상태를 초기화합니다. 필요한 상태는 localStorage나 persistence plugin으로 저장하세요.

이전 버전으로 복원할 수 있나요?

네. DeployPages는 배포 기록을 보관하므로 필요할 때 이전 정적 빌드로 되돌릴 수 있습니다.