Vue CLI: 개발과 배포 환경별로 publicPath 다르게 설정하기 (GitHub Pages)

2020년 2월 작성. Vue CLI는 지금 유지보수 모드이고, Vue 2는 2023년 12월 31일에 지원이 종료됐다. 새 프로젝트는 create-vue(Vite)로 시작한다. 이 글의 방법은 기존 Vue CLI 프로젝트에 쓰고, Vite에서는 아래 «Vite에서는» 항목을 참고한다.

요약

GitHub Pages처럼 하위 경로(/저장소명/)에 배포할 때는, 빌드할 때만 publicPath 를 그 경로로 바꾼다.

// vue.config.js
module.exports = {
  publicPath: process.env.NODE_ENV === "production" ? "/저장소명/" : "/",
};

Vue CLI란

vue.config.js 를 이야기하기 전에 Vue CLI부터 살펴보자. Vue CLI는 «Standard Tooling for Vue.js Development», 즉 Vue 개발에만 집중할 수 있도록 webpack 기반의 개발 환경을 만들어 주는 도구다.

vue.config.js란

vue.config.js 는 개발 서버와 빌드를 담당하는 @vue/cli-service 가 자동으로 읽어 들이는 설정 파일이다. 보통 webpack을 직접 쓸 때는 webpack.config.js 를 수정하지만, Vue CLI에서는 vue.config.js 의 configureWebpack, chainWebpack 옵션으로 webpack 설정까지 바꿀 수 있다.

publicPath란

빌드된 JS, CSS 같은 파일을 어떤 경로 기준으로 불러올지 정하는 옵션이다. 기본값은 / 다. 예를 들어 사이트를 루트(/)가 아니라 /user/ 아래에 배포한다면, 모든 JS와 CSS 파일 경로 앞에 /user/ 가 붙어야 한다. 이때 쓰는 것이 publicPath 다. 빈 문자열('')이나 './' 를 넣으면 상대 경로로 불러온다. 자세한 내용은 공식 문서를 참고한다.

publicPath 설정 방법

프로젝트 루트에 vue.config.js 가 없다면 새로 만들고 아래처럼 적는다.

module.exports = {
  publicPath: "/user/",
};

이미 vue.config.js 가 있다면 module.exports 객체에 publicPath 만 추가하고 원하는 경로를 값으로 적으면 된다.

환경별로 publicPath를 바꿔야 하는 이유

개발 환경과 배포 환경의 경로가 다를 수 있다. 예를 들어 GitHub Pages에 프로젝트 페이지를 올리면 주소가 아래처럼 정해진다.

https://{아이디}.github.io/{저장소명}/

이때 사이트의 루트는 {아이디}.github.io 다. publicPath 를 /{저장소명}/ 으로 설정하지 않으면 JS와 CSS 파일을 불러오지 못해서 흰 화면만 보인다.

반대로 배포에 맞춰 publicPath 를 고정해 두면, 이번에는 로컬 개발 서버에서 JS와 CSS를 불러오지 못한다.

환경별로 publicPath 바꾸기

process.env.NODE_ENV 로 빌드할 때와 개발할 때를 구분한다.

module.exports = {
  publicPath: process.env.NODE_ENV === "production" ? "/저장소명/" : "/",
};

Vue Router의 history 모드를 쓴다면 라우터의 기준 경로도 맞춰야 한다. Vue CLI는 publicPath 값을 process.env.BASE_URL 로 넣어 주므로, 라우터를 만들 때 이 값을 쓴다.

// Vue Router 4
createRouter({ history: createWebHistory(process.env.BASE_URL), routes });
// Vue Router 3 (Vue 2)
new VueRouter({ mode: "history", base: process.env.BASE_URL, routes });

Vite에서는

Vite에서는 vite.config.js 의 base 옵션이 같은 역할을 한다. 빌드 명령일 때만 하위 경로를 쓰도록 나눌 수 있다.

// vite.config.js
import { defineConfig } from "vite";

export default defineConfig(({ command }) => ({
  base: command === "build" ? "/저장소명/" : "/",
}));

정리

process.env.NODE_ENV 조건으로 환경마다 설정을 바꿀 수 있다는 것을 알게 되었다. outputDir, assetsDir 같은 다른 빌드 설정도 같은 방식으로 환경에 따라 바꿀 수 있어서, 개발 환경과 빌드 결과의 경로 문제를 함께 해결할 수 있다.