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

VitePress는 Vue 기반의 현대적인 정적 사이트 생성기로, 빠르고 아름답고 유지보수하기 쉬운 문서 웹사이트 제작에 최적화되어 있습니다. Vite 기반으로 만들어져 개발 경험과 빌드 성능이 뛰어나며, 프로젝트, 라이브러리 혹은 제품을 위한 전문 문서 사이트가 필요한 개발자들에게 탁월한 선택지입니다.

VitePress를 로컬에서 개발하고 테스트할 때는 안정적이고 손쉽게 구성할 수 있는 로컬 웹 개발 환경이 필수적입니다. ServBay는 바로 이런 목적에 맞게 탄생한 솔루션으로, 여러 버전의 Node.js 환경과 고성능 웹 서버(Caddy 또는 Nginx 등)를 결합해 VitePress 프로젝트를 쉽게 서비스할 수 있습니다.

이 문서에서는 ServBay의 통합 환경을 이용하여 VitePress 프로젝트를 처음부터 만들고 구성 및 실행하는 방법, 개발 서버 리버스 프록시 설정, 프로덕션 빌드의 정적 파일 서비스 방법까지 자세히 안내합니다.

VitePress란 무엇인가요?

VitePress는 Vite를 기반으로 하는 정적 사이트 생성기(SSG)로, Vue 3의 강력한 기능과 Vite의 뛰어난 속도를 활용해 정적 웹사이트를 생성합니다. 특히 기술 문서 구축에 강점을 보입니다.

VitePress의 주요 특징 및 장점

초고속 개발 경험: Vite의 핫 모듈 교체(HMR)를 활용하여, 내용을 수정하면 브라우저에서 거의 즉시 결과를 확인할 수 있어 생산성이 극대화됩니다.
Vue 기반: 마크다운 파일 안에서 Vue 컴포넌트를 직접 사용할 수 있어, 문서의 인터랙티브성과 표현력이 대폭 향상됩니다.
쉬운 사용법: 설정이 간단하며 바로 사용할 수 있어, 콘텐츠 제작에 집중할 수 있습니다.
높은 성능: 생성된 정적 파일의 크기가 작고, 로딩 속도가 빨라서 SPA와 유사한 매끄러운 사용자 경험을 제공합니다.
SEO 친화적: 생성된 HTML 구조가 검색 엔진에 잘 노출되며, 커스텀 헤드 태그 설정도 가능합니다.
마크다운 확장 지원: CommonMark와 GitHub Flavored Markdown(GFM)의 모든 기능은 물론, 추가적인 문법도 지원합니다.

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

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

ServBay는 Node.js 버전을 쉽게 관리하고, 웹 서버 설정을 간편하게 해주어 개발/프로덕션 환경 모두에서 VitePress 프로젝트를 손쉽게 서비스할 수 있게 합니다.

사전 준비사항

본격적으로 작업을 시작하기 전에 다음을 준비하세요:

ServBay 설치: 시스템에 ServBay가 정상적으로 설치되어 있어야 합니다. 아직 설치하지 않았다면 ServBay 설치 가이드를 참고하세요.
Node.js 패키지 설치: ServBay에서 원하는 Node.js 버전이 설치 및 활성화되어 있는지 확인하세요. ServBay의 "패키지" 페이지에서 관리할 수 있습니다. 자세한 내용은 Node.js 사용법을 참고하세요.

VitePress 프로젝트 만들기

프로젝트 디렉터리 초기화
먼저 터미널(명령 프롬프트)을 엽니다. ServBay의 기본 웹사이트 루트에 프로젝트 폴더를 만드는 것이 추후 웹사이트 설정에 편리합니다.
macOS:
bash
```
cd /Applications/ServBay/www
mkdir servbay-vitepress-app
cd servbay-vitepress-app
```
1
2
3
Windows:
cmd
```
cd C:\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

혹은 Yarn 사용:

bash

yarn add -D vitepress
yarn vitepress init

초기화 명령을 실행하면 사이트 제목, 설명 등 기본 설정을 안내합니다. 안내에 따라 정보를 입력합니다:

 ┌  Welcome to VitePress!
 │
 ◇  Where should VitePress initialize the config?
 │  ./docs  # 기본 문서 디렉터리, 엔터
 │
 ◇  Site title:
 │  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에 스크립트 추가 (권장)
 │
 └  완료! 이제 npm run docs:dev 명령으로 작성 시작하세요.

초기화 후 servbay-vitepress-app 폴더에 docs 하위 디렉터리가 생성되고, 그 안에 기본 설정파일(.vitepress)과 예시 페이지(index.md, guide/index.md 등)가 만들어집니다. 동시에 package.json에도 docs:dev, docs:build 등의 스크립트가 추가됩니다.

VitePress 프로젝트 내용 수정하기

홈페이지 내용 편집
기본 홈페이지 파일은 docs/index.md에 위치합니다. 원하는 텍스트 에디터로 이 파일을 열고 내용을 수정합니다. 예시:
markdown
```
# Hello ServBay!

ServBay로 VitePress 문서 사이트를 실행해주셔서 환영합니다.

이 사이트는 ServBay에서 서비스되는 VitePress 데모 웹사이트입니다.
```
1
2
3
4
5

개발 모드로 진입

VitePress 개발 시 내장 개발 서버를 활용하면, 핫 리로드 기능으로 실시간 미리보기가 가능해 편리합니다. ServBay의 리버스 프록시 기능을 활용해 개발 서버에 커스텀 도메인으로 접근하고, SSL(HTTPS) 환경도 쉽게 구축할 수 있습니다.

VitePress 개발 서버 실행
프로젝트 폴더(macos: /Applications/ServBay/www/servbay-vitepress-app, windows: C:\ServBay\www\servbay-vitepress-app)에서 다음 명령어로 개발 서버를 특정 포트(예: 8585)로 실행합니다.
bash
```
npm run docs:dev -- --port 8585
```
1
혹은 Yarn:
bash
```
yarn docs:dev --port 8585
```
1
개발 서버가 지정한 포트(8585)에서 실행되고, 터미널에 표시된 예시 주소(http://localhost:8585)로 접속할 수 있습니다.
ServBay 웹사이트(리버스 프록시) 설정
ServBay 대시보드에서 "웹사이트" 페이지로 이동하여 새 웹사이트를 추가합니다.
- 이름: 예를 들어 VitePress 개발사이트 등으로 입력
- 도메인: 브라우저로 접근할 로컬 개발 도메인 입력. ServBay 브랜드 및 충돌 방지를 위해 .servbay.demo 접미사 사용 권장(예시: vitepress-dev.servbay.demo)
- 웹사이트 종류: 리버스 프록시 선택
- IP: 127.0.0.1 입력
- 포트: 1단계에서 지정한 포트(예: 8585) 입력
설정 저장 및 적용 후, ServBay가 자동으로 웹 서버(Caddy/Nginx 등)를 구성해 https://vitepress-dev.servbay.demo 요청을 http://127.0.0.1:8585로 프록시합니다.
개발 사이트 접속하기
이제 브라우저에서 https://vitepress-dev.servbay.demo로 접속하면, VitePress 개발 서버의 사이트를 볼 수 있습니다. ServBay 설정으로 커스텀 도메인, 자동 SSL 인증서가 적용되어 HTTPS로 안전하게 접속할 수 있습니다.

프로덕션 빌드 생성

문서 개발을 마치고 배포할 준비가 되었다면, 최적화된 정적 사이트로 빌드해야 합니다.

프로덕션 빌드 실행
프로젝트 폴더에서 다음 명령어로 프로덕션 빌드를 실행합니다:
bash
```
npm run docs:build
```
1
혹은 Yarn:
bash
```
yarn docs:build
```
1
빌드가 완료되면 마크다운, Vue 컴포넌트 등이 최적화된 HTML/CSS/JS 정적 파일로 컴파일되어, 기본적으로 docs/.vitepress/dist 폴더에 저장됩니다.
ServBay 웹사이트(정적 파일 서비스) 설정
프로덕션 VitePress 사이트는 정적 파일이므로 ServBay의 정적 파일 서비스로 바로 서비스할 수 있습니다.
ServBay 대시보드에서 "웹사이트" 페이지→새 사이트 추가:
- 이름: 예시로 VitePress 프로덕션사이트 등 입력
- 도메인: 프로덕션 사이트용 로컬 도메인 예시(vitepress-prod.servbay.demo)
- 웹사이트 종류: 정적 선택
- 웹사이트 루트 디렉터리: 빌드된 정적 파일 폴더의 절대 경로 입력
  - macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
  - Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
설정 저장 후, ServBay가 웹 서버를 해당 경로의 파일로 서비스합니다.
프로덕션 사이트 접속하기
이제 브라우저에서 https://vitepress-prod.servbay.demo로 접속하면 VitePress 프로덕션 빌드 사이트를 볼 수 있습니다. 역시 커스텀 도메인, 자동 SSL 인증서가 적용되어 안전하게 이용할 수 있습니다.

간편 URL 모드(`cleanUrls: true`) 활용

VitePress는 cleanUrls: true 설정을 지원합니다. 이 옵션을 켜면 페이지 주소에 .html 확장자가 표시되지 않으며(예: /guide/ 또는 /about, /about.html 대신), 이를 제대로 서비스하려면 웹 서버에서 추가 설정이 필요합니다.

ServBay는 Caddy 또는 Nginx 웹 서버를 사용합니다. 아래는 Caddy에서 try_files 지시어를 활용하는 예시입니다.

VitePress 설정에 cleanUrls 활성화하기
VitePress 설정파일(docs/.vitepress/config.mts 또는 docs/.vitepress/config.ts)에서 siteConfig에 cleanUrls 옵션을 추가 또는 수정합니다.
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 설정 영역에 아래 내용을 입력(도메인명/경로는 실제 사용 환경에 맞게 수정)
- macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
- Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

bash

# 실제 도메인 예: vitepress-cleanurl.servbay.demo
vitepress-cleanurl.servbay.demo {
    # Brotli(zstd), gzip 압축 활성화로 속도 향상
    encode zstd gzip

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

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

    # 파일 찾기 핵심: /about → /about, /guide/ → /guide/index.html, /about → /about.html 등 시도
    try_files {path} {path}/index.html {path}.html

    # 사이트 루트 경로 설정
    # macOS: root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
    # Windows: root * C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
    root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist

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

저장 후 변경사항 적용하세요.

간편 URL 사이트 접속하기
이제 https://vitepress-cleanurl.servbay.demo 등으로 접속하면 .html 없이도 해당 페이지에 접속할 수 있습니다. 예를 들어, about.html 대신 https://vitepress-cleanurl.servbay.demo/about로 바로 접근 가능합니다.

요약

이 문서를 통해 ServBay 환경에서 VitePress 문서 웹사이트를 만드는 방법, 개발/배포, 그리고 로컬 개발 서버-프로덕션 서비스 전환 과정을 모두 익혔습니다. ServBay는 Node.js 환경 관리부터 로컬 웹 서버 설정까지 크게 간소화해주며, 개발 단계의 리버스 프록시와 배포 단계의 정적 파일 서비스 모두에 유용합니다. 또한 도메인 커스텀 및 SSL 인증서 발급까지 자동으로 지원합니다.

ServBay와 VitePress의 강력한 조합으로 보다 빠르게, 편리하게, 그리고 신뢰성 있게 고품질 기술 문서 사이트를 개발·운영할 수 있습니다.

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

VitePress란 무엇인가요? ​

VitePress의 주요 특징 및 장점 ​

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

사전 준비사항 ​

VitePress 프로젝트 만들기 ​

VitePress 프로젝트 내용 수정하기 ​

개발 모드로 진입 ​

프로덕션 빌드 생성 ​

간편 URL 모드(cleanUrls: true) 활용 ​

요약 ​

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

VitePress란 무엇인가요?

VitePress의 주요 특징 및 장점

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

사전 준비사항

VitePress 프로젝트 만들기

VitePress 프로젝트 내용 수정하기

개발 모드로 진입

프로덕션 빌드 생성

간편 URL 모드(`cleanUrls: true`) 활용

요약