注意:
last-sync.json狀態檔案會在首次成功同步時自動建立。首次執行時請忽略「找不到檔案」的警告。
作品集自動同步
自動將 GitHub 儲存庫同步至您的作品集網站。
工作流程
步驟 1:收集設定
詢問使用者:
- GitHub 使用者名稱:(預設來自 git config)
- 作品集類型:
static(projects-data.js) 或supabase(API) - 作品集目錄:作品集專案的路徑
- 篩選條件:排除儲存庫(已封存、Fork、特定名稱)
步驟 2:透過 GitHub API 擷取儲存庫
GET /users/{username}/repos?per_page=100&sort=updated&direction=desc
擷取:name、description、html_url、homepage、language、topics、updated_at
篩選排除:
- Fork(除非使用者選擇包含)
- 個人檔案儲存庫(
{username}/{username}) - 已封存的儲存庫
步驟 3:偵測變更
與 last-sync.json(儲存在技能目錄中)進行比對。
- 新的儲存庫:不在上次同步清單中 → 完整處理
- 已更新的儲存庫:
updated_at已變更 → 重新截圖 - 未變更的儲存庫:跳過
步驟 4:擷取螢幕截圖
對於具有 homepage 或部署 URL 的儲存庫:
const { chromium } = require('playwright');
const browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
await page.setViewportSize({ width: 1280, height: 800 });
await page.goto(process.env.URL, { waitUntil: 'networkidle', timeout: 15000 });
await page.screenshot({ path: `/tmp/portfolio-${name}.png`, fullPage: false });
await browser.close();
儲存至作品集的螢幕截圖目錄。
步驟 5:更新作品集資料
靜態 (projects-data.js)
{
title: '{repo.name}',
description: '自動產生: {description}',
tech: '{language},{topics}',
github_url: '{html_url}',
live_url: '{homepage || ""}',
featured: false
}
Supabase
const res = await fetch('https://your-site.com/api/projects', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer {token}' },
body: JSON.stringify(projectData)
});
步驟 6:儲存同步狀態
{
"lastSync": "2026-05-12T18:30:00Z",
"repos": {
"example-repo": { "updated_at": "2026-04-20T10:00:00Z", "screenshot": true }
}
}
步驟 7:回報結果
同步完成:
+ 2 個新的(Cyberian, Image Enhancer)
+ 1 張螢幕截圖已擷取
+ 1 個已更新(Portfolio)
- 0 個錯誤
注意事項
- 螢幕截圖需要 Playwright 和有效的 URL。如果沒有主頁則跳過。
- 絕不變更現有專案的
featured: true— 只有使用者可以將其設為精選。 - 可透過 cron/GitHub Actions 安排每週同步。
錯誤處理
| 原因 | 修正方式 |
|---|---|
| GitHub API 回傳 401 未授權 | 沒有 token 或 token 已過期。設定 GITHUB_TOKEN 環境變數。在 github.com/settings/tokens 使用 public_repo 範圍產生新的個人存取權杖。 |
| GitHub API 速率限制超標 (403) | 未驗證的請求限制為每小時 60 次。已驗證:每小時 5000 次。請加入 token。如果已驗證,請等待重置(檢查 X-RateLimit-Reset 標頭)。 |
儲存庫沒有 homepage 欄位且無部署 URL | 無法擷取螢幕截圖。在輸出中將該儲存庫標記為「無即時預覽」。使用 GitHub URL 作為備用連結。 |
| Playwright 瀏覽器啟動失敗 | 未安裝 Chromium。執行 npx playwright install chromium。在無頭伺服器上,加入 --no-sandbox 標記:chromium.launch({ headless: true, args: ['--no-sandbox'] })。 |
| 螢幕截圖 URL 回傳 404 或超過 15 秒逾時 | 部署 URL 已過時或網站已關閉。為此儲存庫跳過螢幕截圖。將 URL 和錯誤記錄到 failed-screenshots.json 檔案以供手動檢閱。 |
projects-data.js 具有自訂格式,自動產生可能會破壞它 | 使用正則表達式插入可能會損壞手寫程式碼。先讀取檔案以偵測非標準結構。如果偵測到,請加入一個包含新條目的註解區塊,並要求使用者手動合併。 |
| Supabase API 因外部鍵或結構描述約束而插入失敗 | 作品集結構描述可能與自動產生的承載形狀不同。請先讀取 Supabase 資料表結構描述。明確對應欄位(不使用展開運算子)。在提交之前,以回傳 200 的試行 POST 進行驗證。 |
last-sync.json 已損毀或手動編輯 | 在 try-catch 中將其解析為 JSON。如果失敗,將其重新命名為 last-sync.json.bak 並從頭開始全新同步。警告使用者增量偵測已遺失。 |
GitHub API 模式
儲存庫發現
import requests, os
headers = {"Authorization": f"token {os.environ['GITHUB_TOKEN']}"}
# 擷取所有儲存庫(分頁)
repos = []
page = 1
while True:
r = requests.get(f"https://api.github.com/user/repos?per_page=100&page={page}&sort=updated", headers=headers)
batch = r.json()
if not batch: break
repos.extend(batch)
page += 1
# 篩選:僅非 fork、非封存、有描述
candidates = [r for r in repos if not r["fork"] and not r["archived"] and r["description"]]
速率限制
- GitHub API:每小時 5,000 個請求(已驗證)。檢查
X-RateLimit-Remaining標頭。 - 對於擁有 500 個以上儲存庫的儲存庫:使用條件式請求(使用 ETag 的
If-None-Match) - 在螢幕截圖擷取之間休眠 1 秒(避免 GitHub 對資產的速率限制)
Playwright 螢幕截圖模式
from playwright.sync_api import sync_playwright
def capture(url, output_path):
with sync_playwright() as p:
browser = p.chromium.launch()
page = browser.new_page(viewport={"width": 1280, "height": 800})
page.goto(url, timeout=15000, wait_until="networkidle")
page.screenshot(path=output_path, full_page=False)
browser.close()
錯誤復原
- 頁面載入逾時 -> 重試一次,如果仍然失敗則跳過(在輸出中標記)
- 私人儲存庫 -> 跳過(未經授權無法截圖)
- 頁面崩潰 -> 將錯誤狀態擷取為螢幕截圖
- DNS 失敗 -> 跳過並記錄訊息
快取策略
import hashlib, json, os
cache_file = ".sync-cache.json"
cache = json.load(open(cache_file)) if os.path.exists(cache_file) else {}
for repo in repos:
key = hashlib.md5(f"{repo['full_name']}:{repo['pushed_at']}".encode()).hexdigest()
if cache.get(repo['full_name']) == key:
continue # 跳過:自上次同步後無變更
# ... 擷取螢幕截圖,更新條目 ...
cache[repo['full_name']] = key
json.dump(cache, open(cache_file, 'w'))
檢查清單
- GitHub token 在擷取儲存庫前具有正確的範圍(repo, read:user)
- 僅對具有有效 homepage URL 的儲存庫執行螢幕截圖(先進行 HEAD 檢查)
- Playwright 瀏覽器在 finally 區塊中關閉,以防止孤立程序
- 在插入新條目前,保留現有作品集的自訂設定
- 提供試行模式以在不執行情況下預覽變更
來源
- GitHub REST API v3 文件 (docs.github.com/en/rest/repos/repos) — 儲存庫清單、篩選和分頁
- Playwright 文件 (playwright.dev/docs/api/class-playwright) — 無頭瀏覽器啟動、螢幕截圖和檢視區設定
- Supabase JavaScript 客戶端文件 (supabase.com/docs/reference/javascript) — API 插入、更新和驗證模式
- Node.js
fs模組文件 (nodejs.org/api/fs.html) — 使用原子重新命名進行同步狀態安全的檔案讀取/寫入 - 個人存取權杖最佳實踐 (docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) — 範圍、過期和安全儲存
- GitHub Actions cron 排程 (docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) — 每週同步自動化模式
- 「Automate the Boring Stuff with Python」作者 Al Sweigart (No Starch Press, 第 2 版, 2019) — 適用於 JavaScript 自動化任務的自動化可靠性模式
反模式
| 模式 | 問題 | 修正方式 |
|---|---|---|
| 未檢查現有自訂設定就進行同步 | 自動產生的條目可能會覆蓋使用者手動製作的專案描述、精選標記或自訂排序。 | 先讀取目標檔案。偵測非標準結構。對於 featured: true 的條目,保留所有欄位。僅插入或更新新的或已變更的儲存庫。 |
| 不加區別地為每個儲存庫擷取螢幕截圖 | 沒有即時示範的儲存庫會浪費 Playwright 啟動時間(每次約 3 秒)。具有損壞 URL 的儲存庫會產生無用的錯誤螢幕截圖。 | 預先篩選:僅對 homepage 欄位非空且在 HEAD 請求時回傳 200 的儲存庫進行截圖。 |
| 在使用計量或慢速連線時執行同步 | 複製或截取數十個儲存庫的螢幕截圖可能會消耗大量頻寬和時間。 | 以 10 個一批次執行。加入 --dry-run 標記,列出將變更的內容而不執行。 |
| 使用 Supabase anon 金鑰代替 service_role 金鑰進行寫入 | Anon 金鑰具有列級安全性限制,會封鎖更新。 | 謹慎使用 service_role 金鑰。儲存在環境變數中,絕不放在程式碼中。為同步功能加入資料表層級的 RLS 政策。 |
| 同步後未清理 Playwright 瀏覽器程序 | 每個 chromium.launch() 都會產生一個程序。孤立程序會累積記憶體,並可能耗盡系統資源。 | 始終在 finally 區塊中呼叫 browser.close()。在陣列中追蹤已啟動的瀏覽器,並在收到 SIGINT/SIGTERM 時強制關閉。 |
| 將作品集資料路徑硬編碼而不是從設定讀取 | 路徑在不同專案之間會變更。硬編碼的路徑在第一次於不同機器上使用時會失敗。 | 在步驟 1 中詢問作品集目錄。從該基礎路徑推導出 projects-data.js 的路徑。儲存在同步狀態中以供重複使用。 |