靜態網站 → GitHub Pages
完整工作流程:資料 → 自包含 HTML/CSS/JS 頁面 → 瀏覽器驗證 → 發佈至 GitHub Pages。
適用範圍:1 到數百個項目的頁面、單一作者、零執行期依賴。
何時使用
| 是 | 否 |
|---|---|
| 「幫我做一個有這份清單/表格的頁面」、圖庫、資料儀表板 | 需要後端、驗證、資料庫的應用程式 → 先詢問 |
| 「把它發佈到 GitHub/GitHub Pages」 | 由框架(Next、Astro、Hugo)產生的網站 → 遵循框架流程 |
| 以資料形式重現現有頁面(標題、日期、價格…) | 複製第三方網站的設計/CSS/HTML → 拒絕,重新設計一個乾淨的版面 |
不可協商的規則
- 自行設計。 絕不複製第三方網站的 CSS、HTML 或素材。可以參考資訊結構;但不能沿用其視覺風格。
- 事實可以,作品不行。 標題、日期、價格、評分、連結 = 可重複使用的事實資料。編輯性文字、描述、視覺內容 = 受保護:請勿複製。對於圖片,直接連結原始 CDN 而非提交到倉庫(參閱
reference/data-and-ethics.md)。 - 尊重存取保護。
robots.txt禁止爬蟲、Cloudflare/bot 驗證挑戰 → 不得繞過。應尋找官方 API、金鑰,或退化為單純的外部連結。 - 務必在真實瀏覽器中驗證(截圖 + 點擊測試)才能說「完成了」。
- 在倉庫名稱或帳號不明確時,務必先確認再發佈。
- 未經確認,不得建立自訂網域。 如果使用者未指定,詢問他是否要設定 Cloudflare 重新導向以及網域名稱(步驟 6)。絕不能自行臆測子網域或建立任何內容:DNS 是外部可見的副作用。
工作流程
1. 範圍界定 (30 秒)
-
什麼資料、多少項目、一次性更新還是定期更新?
-
預期輸出:一個頁面?排序/搜尋?哪些業務顯示規則?
-
發佈位置:GitHub 帳號、倉庫名稱、公開/私人(免費帳戶的 Pages 要求公開倉庫)。
-
自訂網域 — 若未指定,需明確詢問。 一次提出問題,並附上預設建議:
你想要 Cloudflare 重新導向到
<owner>.github.io(CNAME,proxy 停用)嗎?如果是,請提供子網域/路徑。技能端名稱可自行決定,但網域一經建立即為公開:在沒有明確回應前不得建立任何內容。如果使用者回答「否」,就停留在
https://<owner>.github.io/<repo>/網址,不建立 DNS 記錄。
2. 取得資料
僅一次腳本執行 → 一個 data.json = 單一事實來源,與渲染分離。
python3 fetch_data.py # → data.json
禮儀:請求間隔 0.3–0.7 秒、明確的 User-Agent、遇到 429/5xx 時重試。
詳情與陷阱(PoW Anubis、Cloudflare、模糊比對、無金鑰 API):參閱 reference/data-and-ethics.md。
3. 生成頁面
從範本開始,不要從零開始:
cp .dsh/skills/static-site-publish/templates/{index.html,styles.css,script.js} ./site/
cp .dsh/skills/static-site-publish/templates/build.py ./site/ # data.json → index.html
python3 ./site/build.py
build.py:小型 Python 生成器(使用 f-string +html.escape),將資料注入卡片網格。資料部分無需 JS 執行期。styles.css:預設深色主題、auto-fill minmax()網格、CSS 變數。script.js:即時搜尋 + 排序 + 在開啟時計算顯示規則(使頁面無需重建即可保持正確)。- 所有可在顯示時計算的內容(狀態、相對日期)都應由 JS 處理:這樣就不需要每天重建網站。
- HTML 應在無 JS 時仍可讀,且 JS 應是漸進增強。
4. 驗證
.dsh/skills/static-site-publish/scripts/verify-site.sh ./site/index.html
在 headless Chrome 中開啟頁面,寫入 /tmp/site-shot.png,並執行點擊重疊測試。查看截圖(使用 read_image 工具)後再下結論。
檢查清單:桌面 + 行動裝置渲染、資料完整(計算項目數量)、連結正確、無重疊。
5. 發佈
.dsh/skills/static-site-publish/scripts/publish-gh-pages.sh ./site my-repo-name
腳本內容:gh auth status → git init/commit → gh repo create --source --push → gh api POST /pages → 輪詢 URL 直到回傳 200 → 顯示最終 URL。
Pages 的延遲為 20 到 90 秒:在成功回傳 200 之前,不要斷定「它沒成功」。也要檢查 gh api repos/{owner}/{repo}/pages/builds/latest --jq .status = built。
6. 自訂網域 + Cloudflare
僅在使用者要求時才執行(參閱步驟 1)。DNS 是公開的:不要將模糊的「好」自行解讀為 AI 選擇的網域名稱。
強制順序:先 DNS、再憑證、最後啟用強制 HTTPS。 網站必須已在 *.github.io 上回傳 200 才能開始。
a. 在 Cloudflare 設定 DNS 重新導向(MCP Cloudflare)
必要權杖:範圍 zone.read + dns.write(Zone Read / DNS Edit)。如果缺少,停止執行並要求擴大權限 — 不得繞過。
GET /zones?name=<根網域>→zone.id。如果回傳零個區域:該網域不在這個帳號中,請詢問。GET /zones/{zone_id}/dns_records?name=<完整網域名>→ 如果已存在相同的 CNAME,則不建立任何記錄(冪等性)。POST /zones/{zone_id}/dns_records:
{ "type": "CNAME", "name": "<子網域>", "content": "<owner>.github.io",
"proxied": false, "ttl": 1 }
proxied: false= 僅 DNS,不可協商:Cloudflare proxy 會阻止 GitHub 簽發憑證。- 目標是
<owner>.github.io,結尾無斜線且不含倉庫名稱(例如jamesdadams.github.io,不是.../my-repo)。 ttl: 1= 自動。
- 透過公開解析驗證,而不僅是透過 API:
dig +short <完整網域名> CNAME @1.1.1.1 # → <owner>.github.io.
dig +short <完整網域名> A @1.1.1.1 # → 185.199.108-111 .153
b. 在 GitHub Pages 端設定網域 + 強制 HTTPS
.dsh/skills/static-site-publish/scripts/set-pages-domain.sh <owner>/<repo> <domain> ./site
腳本內容:在網站中寫入 CNAME 檔案(它會存活於重新部署,避免遺失網域)→ PUT /repos/{owner}/{repo}/pages 並帶有 cname → 等待 https_certificate.state = approved → 啟用 https_enforced: true。
⚠️ https_enforced: true 在憑證不存在時會回傳 400。實際延遲:建立 CNAME 後 5 到 20 分鐘。因此腳本會輪詢而非直接失敗。在憑證簽發前,不要手動勾選「強制 HTTPS」,也不要在這段期間內斷定失敗。
c. 最終驗證
curl -sI https://<domain>/ | head -5 # 200 + header server: GitHub.com
然後在瀏覽器中重新打開頁面(步驟 4)使用自訂網域 URL:回傳 200 並不保證相對路徑(styles.css、script.js)能正確解析 — 這是提供給根網域的 project page 的經典陷阱。
7. 使後續更新成為可能
- 將 git 資料夾放在使用者的專案資料夾中(不要放在
/tmp,重開機後會被清除)。 - 在
README.md中記錄:資料來源、如何重新執行提取、哪些是固定的(資料)vs 動態的(由 JS 計算的規則)。 - 明確告知使用者哪些項目不會自動更新。
已遇過的陷阱
| 症狀 | 原因 | 修正 |
|---|---|---|
| 403「Just a moment…」 | Cloudflare 驗證挑戰 | 記錄限制、尋找官方 API 或提供外部連結;不要嘗試繞過 |
| 頁面截斷「Making sure you're not a bot」 | PoW Anubis | 解決挑戰(參閱 reference)或要求使用者匯出資料 |
| 選擇器對所有項目回傳 0 結果 | 錯誤的模式(例如 /games/lib/genre: 而非 /games/lib/popular/genre:) | 印出 HTML 樣本並在 1 個頁面上測試正規表示式,再進行迴圈 |
| 點擊卡片卻未開啟正確連結 | <a> 層被定位的子元素覆蓋 | 在裝飾性元素上設定 pointer-events: none;使用 elementFromPoint 測試 |
| GitHub Pages 前幾分鐘回傳 404 | 正在建立 | 輪詢直到 90 秒 |
| 某一欄資料為空 | 來源端的標籤可變(例如「Released」vs「Early Access」) | 使用容錯模式 + 逐項目記錄,絕不能使用無聲的 except: pass |
https_enforced 回傳 400「certificate does not exist」 | 憑證尚未簽發 | 等待 https_certificate.state = approved(5-20 分鐘),腳本會輪詢 |
| 自訂網域 30 分鐘後仍 404 | CNAME 缺失/錯誤的所有者/倉庫中缺少 CNAME 檔案 | 使用 dig 確認 CNAME,重新執行 set-pages-domain.sh |
| 啟用 proxy 後 HTTPS 損壞 | 記錄被設定為 Proxied | 改回 DNS only(proxied: false),GitHub 憑證無法透過 proxy 驗證 |
| 「Domain is already in use」 | 網域已在同一個帳號的其他倉庫中使用 | 每個倉庫一個自訂網域;先釋放舊的才能重新指派 |
CSS/JS 在自訂網域回傳 404,但在 *.github.io/repo/ 正常 | 在提供給根網域的 project page 上使用了絕對路徑(/styles.css) | 使用相對路徑(styles.css) |
參考資料
reference/data-and-ethics.md— 資料提取、PoW Anubis、Cloudflare、授權、圖片熱連結reference/design-and-verify.md— 最小設計系統、瀏覽器測試、無障礙reference/publish-gh-pages.md—gh指令、命名、網域、疑難排解scripts/publish-gh-pages.sh— 發佈 + 啟用 Pagesscripts/set-pages-domain.sh— 自訂網域 + 強制 HTTPS(在 Cloudflare CNAME 之後)scripts/verify-site.shtemplates/{index.html,styles.css,script.js,build.py}