为 GitHub README 接入实时 Star History 图表:iframe 与 SVG 两种嵌入方案的完整实战
为 GitHub README 接入实时 Star History 图表:iframe 与 SVG 两种嵌入方案的完整实战
Star History 的实时星标历史图表本身是一个单页应用(SPA)产物,而本文要解决的问题是:如何把这份"活的"图表嵌入到你自己的网站、博客乃至 GitHub 仓库 README 中。读完本文,你将掌握两种经过生产验证的嵌入方式——交互式 <iframe> 嵌入与可直接放入 README 的动态 SVG 图片链接,并理解其背后的 Token 轮询、缓存与 SVG 服务端渲染实现原理。
上图来自 Star History 官方博客,展示了图表被嵌入 GitHub README 后呈现在仓库首页的效果。
一个来自 2016 年的 Issue:为什么拖了 6 年才做
早在 2016 年,就有用户提出过希望把 Star History 图表嵌入到自有网站的 Issue。当时因为开发资源有限,加上 GitHub API 对匿名调用者有着严格的速率限制(rate limit),这个需求只能被搁置。
真正让这件事得以重启的契机,是 Star History 完成了一次大规模重构,将前端改造成以 SVG 渲染为核心的架构。重构之后,团队重新评估了"嵌入式图表"的技术路线:既然图表本身就是 SVG,那么只要能解决"数据实时性"与"GitHub API 限流"两个问题,就有机会复刻 GitHub README 上那些开源项目徽章(badge)的成熟模式。
两种嵌入方案的总体取舍
经过调研,Star History 最终提供了两种互补的嵌入方案,分别面向不同的使用场景:
| 方案 | 载体 | 交互性 | 自适应 | 适用位置 | 安全要求 |
|---|---|---|---|---|---|
<iframe> 嵌入 |
前端页面容器 | 高(可交互、实时数据) | 自动 | 自有网站、博客、团队内部面板 | 需要用户提供个人访问令牌 |
| SVG 图片链接 | 图片 URL | 静态展示、数据实时更新 | 固定尺寸 | GitHub README、组织主页 | 由服务端 Token 池解决限流 |
两者不矛盾:文档给出的最终建议是——内网/自有站追求交互性用 iframe,公开展示(尤其是 GitHub README)追求通用性与安全性用 SVG 图片。
iframe 嵌入:四步拿到可直接粘贴的代码
操作步骤
- 打开 Star History 主页并查询一个仓库;
- 点击图表下方的
Embed按钮; - 在弹窗中输入你自己的 GitHub 个人访问令牌(personal access token);
- 点击
Copy按钮,将生成的代码粘贴到你的网站或博客中。
iframe 嵌入代码的生成弹窗界面(图片来自 Star History 官方博客)。
iframe 代码结构与参数解析
从 GenerateEmbedCodeDialog.tsx 的源码可以看到,生成的 iframe 代码具有如下结构:
<iframe style="width:100%;height:auto;min-width:600px;min-height:400px;"
src="{origin}/embed?secret={base64(token)}#{repos}&type=date|timeline[&logscale]&legend=top-left|bottom-right"
frameBorder="0"></iframe>
各部分的生成逻辑值得展开:
secret参数:源码中使用btoa(state.token)对用户令牌做了一次 base64 编码后拼接进 URL。需要特别说明的是,这仅是防"肉眼直接可见"的简单混淆,并非加密——因此 iframe 方案只适合信任的网页环境(如团队内部面板),这正是文档强调的局限之一。#后的 hash 部分:依次拼接store.repos.join("&")(仓库列表)、type=date或type=timeline(图表模式)、可选的&logscale(对数坐标)以及&legend=(图例位置)。把参数放在 hash 中而非 query string,可以避免历史记录污染服务端日志。- 样式:
width:100%;height:auto配合min-width:600px;min-height:400px,让 iframe 在容器内自适应缩放,同时保证小屏下的最小可用尺寸。
iframe 方案的局限(也是 SVG 方案的动机)
iframe 方案虽然好用,但有两个硬伤:
- GitHub 的 Markdown 渲染器禁止
<iframe>标签,导致它无法放进仓库 README 展示在首页; - 令牌安全:虽然 Star History 本身不存储令牌,但令牌会出现在页面源码里,任何查看源码的人都能看到,除非嵌在受信任的平台(如团队内部 dashboard)。
正是这两个局限,催生了第二种方案。
SVG 实时图表:把 README 徽章模式复刻到星标图上
灵感来源:动态生成的 SVG 徽章
团队观察到,大量开源项目 README 上都挂着形形色色的徽章(badge)。调研后发现这些徽章本质上都是动态生成的 SVG 图片——浏览器通过 <img> 或 Markdown 图片语法加载一个返回 image/svg+xml 的 URL 即可渲染。
巧合的是,Star History 本身就在生成 SVG 图表。如果后端能提供一个返回 SVG 的图片链接,就能复刻徽章的成熟模式。
实现:为 SPA 补上一个 Node.js 后端服务
Star History 一直是无后端的纯 SPA。为了提供 SVG 图片服务,仓库中新增了 backend/main.ts 作为 Node.js 服务。其核心思路是:
- 复用前端 SVG 生成代码:图表渲染逻辑位于 shared/packages/xy-chart.tsx,前端和后端共用同一份 XYChart 渲染函数;
- 用 JSDOM 模拟 DOM:后端没有浏览器环境,backend/main.ts 创建了一个
JSDOM文档,把<svg>节点挂进去后调用 XYChart 渲染,再取回outerHTML; - 修复并压缩 SVG:backend/utils.ts 中的
fixJsdomSvgCasing负责修复 JSDOM 会把 SVG 属性名(如feTurbulence、baseFrequency)小写化的问题,随后使用svgo的optimize()做 multipass 压缩,以减小图片体积、加快加载。
GitHub API 限流与 Token 池机制
GitHub API 对匿名调用限制严格,而 SVG 服务端要替所有用户承担请求。仓库的解决方式是 Token 池(token pool),实现在 backend/token.ts:
- 令牌从
token.env文件读取(本地开发可用ENVPATH环境变量指定路径,即ENVPATH=PATH_TO_YOUR_FILE pnpm dev); - 服务启动时,
initTokenFromEnv()会对每个令牌调用一次 GitHub API 做可用性校验,不可用的直接剔除; - 请求按轮询(round-robin)方式从池中取令牌,命中速率限制的令牌会被
markTokenExhausted()标记为冷却 15 分钟(COOLDOWN_MS),冷却期内跳过;全部令牌都被限制时返回 503。
这些令牌来自社区成员捐赠。每次 /svg 请求的数据获取链路是:先查内存缓存 → 未命中则取令牌 → 调用 shared/common/chart.tsx 的 getRepoData() → 并行拉取 star 记录与仓库 logo(base64 内联进 SVG)→ 渲染 → 写缓存。
/svg 接口的参数详解
从 backend/main.ts 的接口实现可以整理出完整的参数表:
| 参数 | 取值 | 默认值 | 说明 |
|---|---|---|---|
repos |
owner/repo,逗号分隔,最多 20 个 |
必填 | 缺失返回 400;仓库名会被小写归一化并 301 重定向到规范 URL(便于 CDN 缓存) |
type |
date / timeline |
date |
也兼容布尔写法 &date 或 &timeline;决定 x 轴按真实日期还是按仓库创建以来经过的天数 |
logscale |
存在即开启(false 除外) |
关闭 | 对数坐标,适合星标数量级差异大的多仓库对比 |
legend |
top-left / bottom-right |
top-left |
图例位置 |
theme |
dark / 其他 |
light |
明暗主题 |
transparent |
true / 其他 |
非透明 | 透明背景,便于叠加到自定义底色上 |
size |
mobile / laptop / desktop |
laptop |
分别对应 600 / 800 / 1000 px 宽度,见 backend/const.ts 与 backend/utils.ts |
示例端点格式:/svg?repos=star-history/star-history&type=timeline&logscale&legend=bottom-right。该接口同时支持 style=landscape1 生成 1200×630 的仓库卡片(用于 OG 图),但默认行为即星标图 SVG。
缓存与性能设计
为了保证"实时更新"与"不过度打 GitHub API"之间的平衡,backend/cache.ts 实现了三层 LRU 缓存,TTL 均为 24 小时:
starData:按仓库缓存 star 记录与 logo,最多 1 GB 内存预算;svgChart:按规范化查询串缓存渲染好的 SVG,最多 400 MB;ogCard:按仓库名缓存 OG 卡片 SVG,最多 200 MB。
同时 /svg 响应头设置 Cache-Control: public, s-maxage=86400, max-age=86400(backend/main.ts),配合 CDN 层缓存;/healthz 端点会返回三组缓存的命中率、内存占用等统计,便于监控图表服务的健康度。
操作步骤:把实时图表放进 GitHub README
- 打开 Star History 主页并查询一个仓库;
- 向下滚动到操作按钮下方的嵌入区域;
- 点击
Copy按钮; - 将代码粘贴到仓库的 README 文件中。
README 的 Markdown 嵌入代码生成区域(图片来自 Star History 官方博客)。
生成的 Markdown 代码与深色模式支持
EmbedMarkdownSection.tsx 展示了实际生成的 Markdown 代码结构:
## Star History
Star History Chart
其中 {API_URL} 为 Star History 的 SVG 服务地址,查询参数同样支持 type、theme、logscale、legend。此外该组件还提供深色模式自适应版本,使用 <picture> 标签按系统配色切换图片:
## Star History
<a href="{当前页面地址}">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="{API_URL}/svg?repos=owner/repo&type=date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="{API_URL}/svg?repos=owner/repo&type=date" />
<img alt="Star History Chart" src="{API_URL}/svg?repos=owner/repo&type=date" />
</picture>
</a>
这样在深色/浅色系统主题下,README 中的图表都会自动匹配观感。图表数据则由服务端缓存 + Token 池按需回源 GitHub API,因此对 README 的访问者而言是"零令牌、零成本"的实时图。
部署形态:静态站 + Web Service 的组合
Star History 前端是纯静态站点,SVG 服务则是一个独立部署的 Web Service 进程(文档中描述为运行在 render.com 上,服务端口为 8080,见 backend/main.ts)。令牌文件在部署平台上以 secret 形式挂载到仓库根目录的 token.env,服务启动时校验并加载(backend/token.ts)。从仓库的 backend/Dockerfile 可以看到服务可容器化运行,GIT_COMMIT 环境变量会被记录进 /healthz 响应,便于定位线上版本。
结语:两种方案的最终选择建议
总结一下,把实时 Star History 图表嵌入网页有两条路线:
- 内网 / 私有网络:需要可自动缩放、可交互、数据实时的图表时,使用
<iframe>嵌入——它原样展示前端图表且无需后端,代价是必须自备个人令牌,且只适合受信任页面。 - 公开展示 / GitHub README:需要向公众展示实时更新的静态星标图时,使用 SVG 图片链接(如
/svg?repos=star-history/star-history&type=Date)——GitHub 原生支持图片渲染,令牌与限流由服务端 Token 池统一消化,任何人都可以安全引用。
这套"iframe + SVG 图片"双方案,本质上是把 2016 年的老 Issue 拆解成了"交互场景"与"展示场景"两个正交问题,并用"服务端复用前端 SVG 渲染 + 社区 Token 池 + 多层缓存"给出了可长期运行的生产级答案。