注意:
last-sync.json状态文件在首次成功同步时自动创建。首次运行时忽略“缺少文件”警告。
作品集自动同步
自动将GitHub仓库同步到您的作品集网站。
工作流程
步骤1:收集配置
询问用户:
- GitHub 用户名:(默认来自git config)
- 作品集类型:
static(projects-data.js)或supabase(API) - 作品集目录:作品集项目的路径
- 过滤器:排除的仓库(已归档、派生、特定名称)
步骤2:通过GitHub API获取仓库
GET /users/{username}/repos?per_page=100&sort=updated&direction=desc
提取:name、description、html_url、homepage、language、topics、updated_at
过滤掉:
- 派生仓库(除非用户选择包含)
- 个人资料仓库(
{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 未授权 | 没有令牌或令牌已过期。设置 GITHUB_TOKEN 环境变量。在 github.com/settings/tokens 生成一个新的个人访问令牌,作用域为 public_repo。 |
| GitHub API 速率限制超出(403) | 未认证的请求限制为60次/小时。认证后:5000次/小时。添加令牌。如果已认证,等待重置(检查 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的dry-run 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个仓库的仓库:使用条件请求(
If-None-Match配合 ETag) - 截图捕获之间休眠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 令牌具有正确的作用域(repo, read:user)
- 仅对具有有效主页 URL(先进行 HEAD 检查)的仓库运行截图
- 在 finally 块中关闭 Playwright 浏览器,以防止孤儿进程
- 在 upsert 新条目之前保留现有作品集自定义
- 提供 dry-run 模式以预览更改而不执行
来源
- 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 插入、upsert 和认证模式
- 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)—— 每周同步自动化模式
- “使用Python自动化繁琐的工作” by Al Sweigart(No Starch Press,第2版,2019年)—— 适用于JavaScript自动化任务的自动化可靠性模式
反模式
| 模式 | 问题 | 修复 |
|---|---|---|
| 在不检查现有自定义的情况下同步 | 自动生成的条目可能会覆盖用户手工制作的项目描述、featured 标志或自定义排序。 | 先读取目标文件。检测非标准结构。对于 featured: true 条目,保留所有字段。仅 upsert 新仓库或已更改的仓库。 |
| 对所有仓库不加区分地截图 | 没有实时演示的仓库浪费 Playwright 启动时间(每个约3秒)。URL 损坏的仓库会产生无用的错误截图。 | 预过滤:仅对 homepage 字段非空且 HEAD 请求返回200的仓库截图。 |
| 在计量或慢速连接上运行同步 | 克隆或截取几十个仓库会消耗大量带宽和时间。 | 每批10个运行。添加 --dry-run 标志,列出将更改的内容而不执行。 |
| 使用 Supabase anon 密钥而不是 service_role 密钥进行写入 | Anon 密钥具有行级安全限制,会阻止 upsert。 | 谨慎使用 service_role 密钥。存储在环境变量中,绝不放在代码中。为同步函数添加表级 RLS 策略。 |
| 同步后不清理 Playwright 浏览器进程 | 每次 chromium.launch() 都会生成一个进程。孤儿进程会积累内存,可能耗尽系统资源。 | 始终在 finally 块中调用 browser.close()。在数组中跟踪已启动的浏览器,并在 SIGINT/SIGTERM 时强制关闭。 |
| 硬编码作品集数据路径而不是从配置读取 | 路径在不同项目之间变化。硬编码路径会在不同机器上的首次使用时中断。 | 在步骤1中询问作品集目录。从该基础派生 projects-data.js 路径。存储在同步状态中以供重复使用。 |