建立 2026-09-15 更新 2026-09-15

開發、建置、預覽

日常只需要記住三個指令。參數 docs 表示專案根目錄；若你把站點初始化在 repo 根目錄，就省略它。

npx vitepress dev docs      # 開發：熱更新
npx vitepress build docs    # 建置：產出靜態檔
npx vitepress preview docs  # 預覽：用正式建置結果開本機伺服器

對應 npm scripts 通常是 docs:dev、docs:build、docs:preview。完整旗標見官方 CLI。

dev：寫作時用

啟動 Vite 開發伺服器，改 Markdown、config 或 Vue 元件會立刻反映。預設網址是 http://localhost:5173。

這時候看到的是「開發模式」，還沒有完整走正式打包。樣式、程式碼分割、資源雜湊檔名都以 build 為準。

build：要上線前用

把每一頁預渲染成 HTML，輸出到 docs/.vitepress/dist（可用 outDir 改）。CI 或平台的「Build command」就跑這一個。

常見失敗原因：

• Node 版本低於官方要求
• base 設錯，資源路徑對不上
• 在 Markdown 裡用了無法在伺服器端渲染的瀏覽器 API（見 在 Markdown 使用 Vue）

preview：上傳前最後看一眼

preview 會拿 dist 開靜態伺服器（預設 http://localhost:4173），行為接近正式站，而不是 dev 的即時編譯。改完內容若沒再 build，preview 不會自動更新。

{
  "scripts": {
    "docs:preview": "vitepress preview docs --port 8080"
  }
}

確認沒有破圖、內部連結 404、以及子路徑 base 下 CSS 有載入，再把 dist 交給 佈署。