使用 ServBay 建立與運行 VitePress 專案

VitePress 是一套現代化、以 Vue 為基礎的靜態網站產生器，專為打造快速、美觀且易維護的文件網站而設計。得益於 Vite 的底層支援，VitePress 提供極佳的開發體驗與高效的編譯效能。對於需要為專案、程式庫或產品建立專業文檔的開發者而言，VitePress 無疑是極佳選擇。

在本機開發及測試 VitePress 項目前，一個穩定且容易設定的本地 Web 開發環境尤為重要。ServBay 為此而生，它整合了多版本的 Node.js 環境與強大的 Web 伺服器（如 Caddy 或 Nginx），讓您的 VitePress 專案可以輕鬆啟動並對外服務。

本文將引導您如何利用 ServBay 的整合開發環境，從零開始建立、設定並運行一個 VitePress 專案，包括設置開發伺服器的反向代理，以及生產環境的靜態檔案服務。

什麼是 VitePress？

VitePress 是一套基於 Vite 的靜態網站產生器（SSG, Static Site Generator），結合 Vue 3 的強大擴展性與 Vite 超快速的編譯效能，尤其適合用來打造技術文件網站。

VitePress 主要特色與優勢

• 開發體驗極速回饋：仰賴 Vite 熱模組替換（HMR），修改內容後幾乎能瞬間預覽到結果，提升開發效率。
• Vue 驅動：可在 Markdown 文件中直接使用 Vue 元件，讓文件互動性與表現力大增。
• 簡單易上手：配置簡便、開箱即用，專注於內容撰寫。
• 高效能：產出檔案精簡，載入迅速，結合內建客戶端路由，實現 SPA 級流暢體驗。
• SEO 友善：產生的 HTML 結構利於搜尋引擎索引，支援自訂 head 標籤。
• Markdown 強化：支援 CommonMark 與 GitHub Flavored Markdown (GFM) 完整語法，並內建多項便利語法糖。

透過 VitePress，您可以輕鬆打造高品質且高效能的技術文件網站。

使用 ServBay 建立與運行 VitePress 專案

ServBay 讓您輕鬆管理多版本 Node.js，並能快速設定 Web 伺服器，無論是開發環境下的本機服務，還是生產環境的靜態資源，VitePress 專案都能順暢運作。

前置需求

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

1. 安裝 ServBay：請於您的 macOS 系統正確安裝好 ServBay。如尚未安裝，請參考 ServBay 安裝指南。
2. 安裝 Node.js 套件：請在 ServBay 裡安裝並啟用所需的 Node.js 版本。可在 ServBay 控制台「套件」頁面管理。詳情參見 使用 Node.js。

建立 VitePress 專案

1. 初始化專案目錄

   先開啟您的終端機程式。建議在 ServBay 預設網站根目錄 /Applications/ServBay/www 下建立專案資料夾，以利之後配置 ServBay 網站。

   cd /Applications/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

   初始化命令會帶您完成專案基本設定，例如網站標題、描述等。請依提示輸入對應資訊： :::no-line-numbers ┌ 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 的反向代理功能，您能用自訂網域進行開發預覽，同時享受自動 SSL 憑證。

1. 啟動 VitePress 開發伺服器

   在終端機於專案根目錄 /Applications/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. 產生生產版本

   在終端機，於專案根目錄 /Applications/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。
   • 網站型態：選擇 靜態。
   • 網站根目錄：填入剛才編譯產生檔案的目錄絕對路徑 /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist。

   完成並儲存，ServBay 會設定 Web 伺服器將指定目錄的靜態檔案直接對外提供下載。

3. 存取生產站點

   現在您可直接在瀏覽器輸入 https://vitepress-prod.servbay.demo 來存取生產網站內容。同樣可透過 ServBay 自動申請網域與 SSL 證書，確保 HTTPS 安全通訊。

啟用簡潔 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-prod.servbay.demo）。

   • 點選編輯。
   • 勾選 自訂設定。
   • 在 Caddy 設定區塊貼上下方範例。請將 servbay-vitepress-test.prod 替換成您實際網域，/Applications/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. 直接對應路徑 (ex: /about -> /about)
       # 2. 尋找此目錄下 index.html (ex: /guide/ -> /guide/index.html)
       # 3. 尋找路徑加 .html 檔案 (ex: /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # 指定靜態網站根目錄
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # 啟用靜態檔案服務
       file_server
   }

   設定後，請儲存與套用調整。

3. 存取啟用簡潔 URL 的網站

   此時可於瀏覽器輸入設定網域（如 https://vitepress-cleanurl.servbay.demo），且針對啟用 cleanUrls 的頁面能直接以無 .html 副檔名的網址存取，例如想進入 about.html 頁，鍵入 https://vitepress-cleanurl.servbay.demo/about 即可。

總結

透過本教學，您已學會如何在 ServBay 環境下建立、開發與部署 VitePress 文件網站。ServBay 顯著簡化了 Node.js 環境管理與本機 Web 伺服器配置，無論是開發模式反向代理，還是生產環境靜態服務，都能輕鬆應對，並自動提供方便的自訂網域及 SSL 憑證。

結合 ServBay 與 VitePress 的強大動能，您能更高效打造和維護高品質的技術文檔網站。