Skip to main content

GitHub Pages 與 REPO 結構理解

1. REPO（Repository）與 GitHub Pages 的本質差異​

  • REPO：用來儲存原始碼、設定檔、文檔等開發相關資源，主要供開發者使用與版本控制。
  • GitHub Pages：用來發佈靜態網站，直接提供給瀏覽器讀取，通常只包含 HTML、CSS、JavaScript 等編譯後成果檔案。

兩者用途不同，且通常分別位於不同的 Git 分支：

  • main 分支（或 master 分支）：存放開發原始碼。
  • gh-pages 分支：存放生成後的靜態網站成品，供 GitHub Pages 部署使用。

運作模式：從 REPO 的指定分支或資料夾中擷取內容，生成 GitHub Pages 網站。

2. 為什麼建立 GitHub Pages 必須先有 REPO？​

GitHub Pages 必須有一個來源倉庫，才能從中抓取內容生成網站。因此，即使只是單純展示靜態網站，仍必須建立 REPO 作為基礎。

若沒有 REPO，GitHub Pages 將無法啟用，也無法對外提供網站服務。

npm deploy 自定義原理

1. npm run deploy 並非 npm 官方內建指令​

在 Node.js 與 npm 生態系中，npm run deploy 是在 package.json 的 scripts 區塊中自定義的指令名稱，並非 npm 標準內建的功能。

範例：

{
  "scripts": {
    "deploy": "gh-pages -d build"
  }
}

此例中，npm run deploy 本質上是執行 gh-pages -d build 這段指令。

注意：deploy 只是慣例命名，可以自由取名，例如 "publish-site"、"upload-to-pages" 皆可。

2. deploy 通常用於什麼場景？​

在許多 Node.js 架構（如 React、Vue、Docusaurus）中，deploy 通常代表：

  • 執行建置（npm run build）
  • 將建置出來的成品資料夾（如 build/、dist/）推送到 gh-pages 分支
  • 讓 GitHub Pages 根據 gh-pages 分支內容生成網站

但具體做什麼完全取決於 package.json 中的腳本定義。

小結與實務應用

  • REPO 負責儲存原始碼與建置前的開發資源
  • GitHub Pages 從 REPO 指定位置擷取建置後的靜態網站檔案供外界訪問
  • deploy 指令是自定義行為，每個專案都應在 README 中明確說明 deploy 的定義與運作內容

理解這個結構，可以避免部署錯誤與誤解，也能讓專案維護更清晰高效。

適用場景：使用 Docusaurus、React、Vue、Next.js 或其他任何基於 Node.js 架構的靜態網站專案，並計畫使用 GitHub Pages 部署。