Skip to content

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

GitHub Pages

適合開源專案與個人文件站：推到預設分支就自動建置。官方工作流程見〈部署〉，以下是必須對齊的幾件事。

先設 base

若網站網址是 https://<user>.github.io/<repo>/，config 必須是：

export default {
  base: '/<repo>/',
}

開頭與結尾的斜線都要。設成 '/' 或漏了結尾 /，CSS 與 JS 會 404，頁面只剩沒樣式的 HTML。

若使用自訂網域（https://docs.example.com/）且站點在網域根路徑，則 base 維持 '/'。

Actions 在做什麼

在 .github/workflows/deploy.yml 裡，核心是：

  1. Checkout（若啟用 lastUpdated 要 fetch-depth: 0，才能算 Git 日期）。
  2. 安裝 Node（官方範例使用較新的 Node 22／24）與依賴。
  3. npm run docs:build。
  4. 把 docs/.vitepress/dist 上傳為 Pages artifact。
  5. 用 actions/deploy-pages 發佈。

完整 YAML 請直接複製官方範例，再依 npm／pnpm／yarn 取消對應註解。工作流程會隨 Actions 版本微調，以官方文件為準比抄舊教學可靠。

倉庫設定

  1. Settings → Pages → Build and deployment → Source 選 GitHub Actions（不要選「Deploy from a branch」去指 gh-pages，除非你自己另寫流程）。
  2. 把 workflow 推進預設分支，等綠色勾勾。
  3. 網站會出現在 https://<user>.github.io/<repo>/。

輸出目錄預設是 docs/.vitepress/dist。若你把 VitePress 初始化在 repo 根目錄，路徑改成 .vitepress/dist，workflow 的 path 也要一起改。