使用 ServBay 建立與運行 VitePress 專案

VitePress 是一款由 Vue 驅動的現代靜態網站產生器，設計目標是打造快速、美觀且易於維護的文件網站。它以 Vite 為基礎，提供卓越的開發體驗與建置效能。對於需要為專案、函式庫或產品建立專業文件的開發者來說，VitePress 是最佳選擇之一。

在本機開發與測試 VitePress 文件時，擁有一個可靠且易於設定的本機 Web 開發環境尤為重要。ServBay 正是為此而打造，它整合多版本 Node.js 環境以及強大的 Web 伺服器（如 Caddy 或 Nginx），讓您的 VitePress 專案能輕鬆獲得服務支援。

本文將教您如何利用 ServBay 的整合環境，從零開始建立、設定與運行 VitePress 專案，包括設置開發伺服器的反向代理，以及正式建置後的靜態檔案服務。

什麼是 VitePress？

VitePress 是一款基於 Vite 的靜態網站產生器（SSG），結合 Vue 3 的彈性與 Vite 的極速效能，非常適合打造技術文件網站。

VitePress 的主要特色與優勢

• 極速開發體驗：利用 Vite 的熱模組替換（HMR），內容修改後幾乎立即在瀏覽器中更新，大幅提升開發效率。
• Vue 驅動：可在 Markdown 文件中直接使用 Vue 元件，強化文件的互動性與表現力。
• 簡單易用：設定簡單，開箱即用，專注於內容創作。
• 高效能：產生的靜態檔案體積小、載入快，加上內建的前端路由，體驗如同單頁應用。
• SEO友善：產生的 HTML 結構利於搜尋引擎收錄，且支援自訂 header 標籤。
• Markdown 增強：全面支援 CommonMark 及 GitHub Flavored Markdown (GFM)，並提供額外語法糖。

使用 VitePress，開發者可以輕鬆打造高品質、高效能的文件網站。

使用 ServBay 建立與運行 VitePress 專案

ServBay 提供便利的 Node.js 版本管理與 Web 伺服器設定，協助您的 VitePress 專案，不論開發時的本機伺服器或正式建置的靜態網站皆可輕鬆運作。

前置條件

開始之前，請確認已完成下列準備：

1. 安裝 ServBay：您的作業系統已成功安裝 ServBay。若尚未安裝，請參考 ServBay 安裝指南。
2. 安裝 Node.js 軟體包：在 ServBay 中，確認您已安裝並啟用所需版本的 Node.js 軟體包。可於 ServBay 控制台的「軟體包」頁面管理，詳見 使用 Node.js。

建立 VitePress 專案

1. 初始化專案目錄

   首先，開啟您的終端機。建議於 ServBay 的預設網站根目錄下建立專案資料夾，以便後續網站設定。

   macOS：

   cd /Applications/ServBay/www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

   Windows：

   cd C:\ServBay\www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

2. 安裝 VitePress 並初始化設定

   於專案目錄 servbay-vitepress-app 中，使用 npm 或 yarn 安裝 VitePress 作為開發相依，並執行初始化指令。

   npm add -D vitepress
   npx vitepress init

   或使用 Yarn：

   yarn add -D vitepress
   yarn vitepress init

   初始化指令會引導您完成基本設定，例如網站名稱、描述等。請依提示輸入資料：

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # 預設文件目錄，直接按 Enter 確認
    │
    ◇  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 專案內容

1. 編輯首頁內容

   VitePress 預設首頁為 docs/index.md。可用任何文字編輯器打開此檔案修改內容，例如改為：

   # Hello ServBay!
   
   歡迎使用 ServBay 運行您的 VitePress 文件網站。
   
   這是一個利用 VitePress 建立的本機展示站台，由 ServBay 提供服務。

進入開發模式

在編輯 VitePress 網站時，通常直接使用內建開發伺服器，其支援熱更新、可即時預覽修改。接著，可利用 ServBay 的反向代理功能，透過自訂網域來存取開發伺服器，並同時享有 ServBay 的 SSL 加密服務。

1. 啟動 VitePress 開發伺服器

   在終端機中，確認位於專案根目錄（macOS：/Applications/ServBay/www/servbay-vitepress-app，Windows：C:\ServBay\www\servbay-vitepress-app）。輸入下列指令啟動開發伺服器並指定埠號（如 8585）：

   npm run docs:dev -- --port 8585

   或以 Yarn 執行：

   yarn docs:dev --port 8585

   開發伺服器將於本機指定埠口（如 8585）啟動，終端機會顯示服務地址，通常為 http://localhost:8585。

2. 設定 ServBay 網站（反向代理）

   前往 ServBay 控制台的「網站」頁面，新增一筆網站設定。

   • 名稱：輸入易識別的名稱，例如 VitePress 開發站台。
   • 網域：輸入欲於瀏覽器使用的本機開發網域。建議使用 .servbay.demo 後綴，如 vitepress-dev.servbay.demo。
   • 網站類型：選擇 反向代理。
   • IP：填入 127.0.0.1（代表本機）。
   • 埠號：填入上一步指定的埠號，如 8585。

   完成後儲存並應用設定。ServBay 會自動讓 Web 伺服器（Caddy 或 Nginx）將 https://vitepress-dev.servbay.demo 的請求轉發至 http://127.0.0.1:8585。

3. 瀏覽開發站台

   現在即可於瀏覽器輸入設定的網域 https://vitepress-dev.servbay.demo，即可看到 VitePress 開發伺服器提供的網站內容。透過 ServBay，您同時啟用自訂網域並取得由 ServBay User CA 簽發的 SSL 憑證，享有 HTTPS 加密。

建置正式版本

當文件編輯完畢、準備公開時，需要進行最終編譯優化產生靜態版本。

1. 產生正式版文件

   在終端機中，確認目前目錄在專案根目錄（macOS：/Applications/ServBay/www/servbay-vitepress-app，Windows：C:\ServBay\www\servbay-vitepress-app）。輸入以下指令開始建置：

   npm run docs:build

   或使用 Yarn：

   yarn docs:build

   建置過程會將 Markdown 文件、Vue 元件等打包成最佳化的靜態 HTML、CSS、JavaScript 等檔案。產生之結果預設放在 docs/.vitepress/dist 資料夾。

2. 設定 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 Web 伺服器會直接以指定根目錄提供靜態網站。

3. 瀏覽正式站台

   現於瀏覽器輸入設定好的網域 https://vitepress-prod.servbay.demo，即可進入 VitePress 正式版網站。ServBay 會自動提供自訂網域及 SSL 加密。

啟用簡潔 URL 模式 (cleanUrls: true)

VitePress 支援 cleanUrls: true 設定，可讓產生的頁面連結不帶 .html 副檔名（如 /guide/ 取代 /guide/index.html，或 /about 取代 /about.html）。Web 伺服器需額外設定方能正確處理此種請求。

ServBay 採用 Caddy 或 Nginx 作為伺服器，以下以 Caddy 範例介紹，可利用 try_files 指令自動嘗試查找相對檔案（含目錄下 index.html 或加 .html 的頁面）。

1. 於 VitePress 設定中啟用 cleanUrls

   編輯 VitePress 設定檔（docs/.vitepress/config.mts 或 docs/.vitepress/config.ts），於 siteConfig 新增或修改 cleanUrls 參數：

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... 其他設定
     cleanUrls: true, // 啟用簡潔 URL
     // ... 其他設定
   })

   重新執行 npm run docs:build 產生正式版。

2. 設定 ServBay 網站（自訂 Caddy 設定）

   前往 ServBay 控制台「網站」頁面，找到您設定的 VitePress 正式站台（如 vitepress-prod.servbay.demo）。

   • 點選編輯。
   • 勾選 自訂設定 選項。
   • 在 Caddy 設定文字區域，輸入或貼上以下設定。請將 servbay-vitepress-test.prod 替換成實際網域，網站根目錄路徑亦一併更改為您的實際位址：
     • macOS：/Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows：C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   # 請替換為您的實際網域，例如 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. 直接對應路徑 (如 /about -> /about)
       # 2. 嘗試目錄下 index.html (如 /guide/ -> /guide/index.html)
       # 3. 嘗試加 .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
   }

   儲存並應用設定。

3. 瀏覽簡潔 URL 模式站台

   現可直接輸入網域（如 https://vitepress-cleanurl.servbay.demo），啟用 cleanUrls 的頁面即可直接使用不含 .html 副檔名的 URL，如訪問 about.html 可直接用 https://vitepress-cleanurl.servbay.demo/about。

結論

依照本文教學，您已學會如何於 ServBay 環境下建立、開發、部署 VitePress 文件網站。ServBay 讓 Node.js 管理和本機 Web 伺服器設定變得更為容易，不論是開發期的反向代理，或正式建置的靜態網站服務，都能輕鬆上手，更自動賦予自訂網域與 SSL 憑證。

結合 ServBay 與 VitePress 的強大組合，您可更高效打造並維護高品質的技術文件。