ServBay로 VitePress 프로젝트 생성 및 실행하기

VitePress는 Vue 기반의 최신 정적 사이트 생성기로, 빠르고 아름다우며 유지보수가 쉬운 문서 사이트를 구축하기 위해 설계되었습니다. Vite를 기반으로 하여 우수한 개발 경험과 뛰어난 빌드 성능을 제공합니다. 프로젝트, 라이브러리, 제품을 위한 전문 문서를 만들고자 하는 개발자에게 VitePress는 탁월한 선택입니다.

로컬에서 VitePress 개발 및 테스트를 진행하려면, 안정적이고 설정이 쉬운 로컬 웹 개발 환경이 필수입니다. ServBay는 바로 이러한 목적에 최적화된 솔루션으로, 다양한 버전의 Node.js 환경과 강력한 웹 서버(Caddy 또는 Nginx)를 통합 제공하여 VitePress 프로젝트를 쉽게 서비스할 수 있습니다.

이 문서에서는 ServBay의 통합 환경을 활용하여, VitePress 프로젝트를 0부터 생성, 설정, 실행하는 방법을 안내합니다. 개발 서버의 리버스 프록시 설정과 프로덕션 빌드용 정적 파일 서비스 구성까지 단계별로 다룹니다.

VitePress란?

VitePress는 Vite를 기반으로 한 정적 사이트 생성기(SSG)이며, Vue 3의 강력함과 Vite의 속도, 효율성을 접목해 기술 문서 사이트 제작에 최적화되어 있습니다.

VitePress의 주요 특징과 장점

압도적으로 빠른 개발 경험: Vite의 HMR(핫 모듈 교체) 덕분에 수정사항이 거의 즉시 브라우저에 반영되어, 생산성이 대폭 향상됩니다.
Vue 기반: Markdown 파일 안에서 직접 Vue 컴포넌트 사용이 가능하여, 문서의 상호작용성과 표현력이 놀랍게 확장됩니다.
간편한 사용성: 복잡한 설정 없이 바로 시작할 수 있으며, 콘텐츠 작성에 집중할 수 있습니다.
높은 성능: 빌드된 정적 파일은 작고, 로딩 속도가 매우 빠르며 내장 클라이언트 라우터를 통해 싱글 페이지 앱처럼 부드러운 사용자 경험을 제공합니다.
SEO 친화적: 생성된 HTML은 검색 엔진에서 쉽게 크롤링할 수 있도록 구조화되어 있으며, 커스텀 헤드 태그도 지원합니다.
Markdown 확장 기능: CommonMark 및 GitHub Flavored Markdown(GFM)의 모든 기능을 지원하면서, 추가적인 문법 확장도 제공합니다.

VitePress를 사용하면 개발자는 쉽고 빠르게 고품질, 고성능의 문서 웹사이트를 구축할 수 있습니다.

ServBay로 VitePress 프로젝트 만들고 실행하기

ServBay를 통해 Node.js 버전 관리와 웹 서버 설정을 쉽게 하고, VitePress 프로젝트의 개발 서버 및 정적 파일 서빙 환경을 손쉽게 구축할 수 있습니다.

사전 준비

아래 조건을 준비해 주세요.

ServBay 설치: macOS 시스템에 ServBay가 정상적으로 설치되어 있어야 합니다. 설치가 필요하다면 ServBay 설치 가이드를 참고하세요.
Node.js 패키지 설치: ServBay에서 원하는 버전의 Node.js 패키지가 설치되어 있고 사용 가능해야 합니다. ServBay 콘솔의 "패키지" 섹션에서 관리할 수 있습니다. 자세한 사용법은 Node.js 사용법을 참고하세요.

VitePress 프로젝트 생성

프로젝트 디렉토리 초기화
터미널을 열고, ServBay의 기본 웹사이트 루트인 /Applications/ServBay/www 아래에 프로젝트 폴더를 만드는 것이 좋습니다. 그래야 ServBay 사이트 설정이 편리합니다.
bash
```
cd /Applications/ServBay/www
mkdir servbay-vitepress-app
cd servbay-vitepress-app
```
1
2
3
VitePress 설치 및 기본 설정 초기화
servbay-vitepress-app 프로젝트 디렉토리에서 npm 또는 yarn으로 VitePress를 개발 의존성으로 추가하고, 초기화 명령을 실행합니다.
bash
```
npm add -D vitepress
npx vitepress init
```
1
2
Yarn을 쓰는 경우:
bash
```
yarn add -D vitepress
yarn vitepress init
```
1
2
초기화 명령은 사이트 제목, 설명 등 기본 정보를 입력하도록 안내합니다: :::no-line-numbers ┌ Welcome to VitePress! │ ◇ Where should VitePress initialize the config? │ ./docs # 기본 문서 디렉토리, 엔터 키로 진행 │ ◇ Site title: │ ServBay VitePress Demo # 사이트 제목 입력, 예: ServBay VitePress Demo │ ◇ Site description: │ A VitePress site running on ServBay # 사이트 설명 입력 │ ◇ Theme: │ Default Theme # 테마 선택, 기본 테마로 진행 │ ◇ Use TypeScript for config and theme files? │ Yes # TypeScript 설정 사용 여부, 선호도에 따라 선택 │ ◇ Add VitePress npm scripts to package.json? │ Yes # package.json에 스크립트 추가, 추천: Yes │ └ Done! Now run npm run docs:dev and start writing. :::
설정이 완료되면, VitePress가 servbay-vitepress-app 디렉토리 내에 docs 하위 폴더와 기본 설정 파일(.vitepress), 예시 페이지(index.md, guide/index.md 등)를 생성합니다. 그리고 package.json에는 docs:dev, docs:build 같은 스크립트가 추가됩니다.

VitePress 프로젝트 콘텐츠 수정

메인 페이지 내용 편집
VitePress의 기본 메인 페이지 파일은 docs/index.md입니다. 원하는 텍스트 에디터로 파일을 열고, 내용을 자유롭게 수정할 수 있습니다. 예를 들어 다음과 같이 변경해보세요:
markdown
```
# Hello ServBay!

ServBay를 사용해 VitePress 문서 사이트를 실행해보세요.

이 사이트는 VitePress로 만든 로컬 데모 사이트이며, ServBay를 통해 서비스됩니다.
```
1
2
3
4
5

개발 모드로 진입하기

VitePress의 내장 개발 서버를 활용하면 실시간 프리뷰(핫 리로드)가 지원되어 개발이 매우 편리합니다. ServBay가 제공하는 리버스 프록시 기능을 통해 커스텀 도메인과 SSL로 개발 서버에 접속할 수 있습니다.

VitePress 개발 서버 구동
터미널에서 /Applications/ServBay/www/servbay-vitepress-app 경로에 위치한 상태에서 아래 명령을 실행합니다(예시 포트: 8585).
bash
```
npm run docs:dev -- --port 8585
```
1
또는 Yarn으로:
bash
```
yarn docs:dev --port 8585
```
1
개발 서버가 시작되면, 일반적으로 http://localhost:8585와 같이 표시됩니다.
ServBay 사이트 설정(리버스 프록시)
ServBay 콘솔에서 "사이트" 페이지로 이동해, 새 사이트 구성을 추가하세요.
- 이름: 예) VitePress 개발 사이트
- 도메인: 브라우저에서 접근할 로컬 개발 도메인 (브랜드 일관성 및 충돌 방지를 위해 .servbay.demo 추천), 예: vitepress-dev.servbay.demo
- 사이트 타입: 리버스 프록시 선택
- IP: 127.0.0.1
- 포트: 앞서 개발 서버를 띄운 포트 번호, 예: 8585
설정 후 저장 및 적용하면, ServBay가 Caddy/Nginx 등 웹 서버를 자동 구성하여 https://vitepress-dev.servbay.demo로 오는 요청을 http://127.0.0.1:8585로 전달합니다.
개발 사이트 접속
브라우저에서 https://vitepress-dev.servbay.demo로 접속해보세요. 개발 서버의 콘텐츠가 보이며, ServBay가 발급한 SSL 인증서 덕분에 HTTPS로 안전하게 접속할 수 있습니다.

프로덕션 빌드

문서 작업이 마무리되어 실제 배포를 준비할 때는 최적화된 정적 파일을 빌드해야 합니다.

프로덕션 빌드 실행
터미널에서 프로젝트 루트(/Applications/ServBay/www/servbay-vitepress-app)에서 아래 명령을 실행하세요.
bash
```
npm run docs:build
```
1
또는 Yarn 사용 시:
bash
```
yarn docs:build
```
1
빌드가 완료되면, 정적 사이트 파일(HTML, CSS, JS 등)이 docs/.vitepress/dist 폴더에 생성됩니다.
ServBay 사이트 설정(정적 파일 서비스)
프로덕션 모드의 VitePress 사이트는 순수 정적 파일 모음이므로, ServBay의 정적 파일 서빙 기능으로 바로 서비스할 수 있습니다.
ServBay 콘솔의 "사이트"에서 새 사이트 구성을 추가하고:
- 이름: 예) VitePress 프로덕션 사이트
- 도메인: 배포용 로컬 도메인, 예 vitepress-prod.servbay.demo
- 사이트 타입: 정적
- 사이트 루트 디렉토리: 빌드된 정적 파일의 절대 경로(/Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist)
저장 및 적용하면, 웹 서버가 지정한 경로에서 정적 파일을 직접 서비스할 수 있게 됩니다.
프로덕션 사이트 접속
브라우저에서 https://vitepress-prod.servbay.demo로 방문하면, 프로덕션 빌드 사이트가 보입니다. 도메인/SSL 관리도 ServBay가 자동 처리합니다.

클린 URL 모드(`cleanUrls: true`)로 동작하기

VitePress는 cleanUrls: true 옵션을 지원하여, .html 확장자 없이 /about, /guide/ 등 깔끔한 URL을 제공합니다. 이를 위해 웹 서버 또한 추가 설정이 필요합니다.

ServBay는 Caddy 또는 Nginx를 사용하며, 아래는 Caddy의 try_files 명령을 활용한 예시입니다. 이는 요청 URL에 대해 실제 파일, 디렉토리 내 index.html, 혹은 .html 파일을 자동으로 탐색하여 제공합니다.

VitePress에서 cleanUrls 활성화
VitePress 설정 파일(docs/.vitepress/config.mts 또는 docs/.vitepress/config.ts)에서 siteConfig 내에 아래 옵션을 추가/수정하세요:
typescript
```
// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  // ... 기타 설정
  cleanUrls: true, // 클린 URL 활성화
  // ... 기타 설정
})
```
1
2
3
4
5
6
7
8
이후 npm run docs:build로 다시 프로덕션 빌드를 진행합니다.

ServBay 사이트에 Caddy 커스텀 설정 적용

ServBay 콘솔 "사이트" 페이지에서, VitePress 프로덕션 사이트(예: vitepress-prod.servbay.demo)의 설정을 편집하세요.

커스텀 설정 체크
Caddy 설정 입력란에 아래와 같이 입력합니다. (servbay-vitepress-test.prod, 경로 등은 실제 값으로 수정)

bash

# 실제 도메인으로 변경, 예: vitepress-cleanurl.servbay.demo
vitepress-cleanurl.servbay.demo {
    # Brotli (zstd), Gzip 압축 활성화 (속도 개선)
    encode zstd gzip

    # ServBay 기본 로그 설정 포함 (디버깅 시 유용)
    import set-log vitepress-cleanurl.servbay.demo

    # ServBay 내부 SSL 인증서 자동 처리
    tls internal

    # 핵심 설정: 요청 파일 탐색 규칙
    # 1. 요청 경로와 동일한 파일
    # 2. 요청 경로의 index.html
    # 3. 요청 경로 + .html 파일
    try_files {path} {path}/index.html {path}.html

    # 사이트 루트 디렉토리 지정
    root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist

    # 정적 파일 서비스 활성화
    file_server
}

저장 후 적용합니다.

클린 URL 방식 접속 테스트
브라우저에서 https://vitepress-cleanurl.servbay.demo 같은 도메인으로 접속, .html 없는 /about 등 경로로 정상 접속되는지 확인할 수 있습니다.

마무리

이 가이드에서는 ServBay 환경에서 VitePress 문서 사이트를 생성, 개발, 배포하는 전 과정을 다뤘습니다. ServBay는 Node.js 환경 관리부터 로컬 웹 서버 설정, 개발용 리버스 프록시, 프로덕션 빌드 정적 파일 서비스까지 모두 단순화하며, 커스텀 도메인 및 SSL 인증서 지원도 자동으로 제공합니다.

ServBay와 VitePress의 강력한 결합을 통해 고품질의 기술 문서를 더욱 쉽고 효율적으로 관리하고 배포해 보세요.

ServBay로 VitePress 프로젝트 생성 및 실행하기 ​

VitePress란? ​

VitePress의 주요 특징과 장점 ​

ServBay로 VitePress 프로젝트 만들고 실행하기 ​

사전 준비 ​

VitePress 프로젝트 생성 ​

VitePress 프로젝트 콘텐츠 수정 ​

개발 모드로 진입하기 ​

프로덕션 빌드 ​

클린 URL 모드(cleanUrls: true)로 동작하기 ​

마무리 ​