为 GitHub README 接入实时 Star History 图表:iframe 与 SVG 两种嵌入方案的完整实战

原创2026-10-06 13:10:061,833 阅读
文章标签:开发工具数据可视化

为 GitHub README 接入实时 Star History 图表:iframe 与 SVG 两种嵌入方案的完整实战

Star History 的实时星标历史图表本身是一个单页应用(SPA)产物,而本文要解决的问题是:如何把这份"活的"图表嵌入到你自己的网站、博客乃至 GitHub 仓库 README 中。读完本文,你将掌握两种经过生产验证的嵌入方式——交互式 <iframe> 嵌入与可直接放入 README 的动态 SVG 图片链接,并理解其背后的 Token 轮询、缓存与 SVG 服务端渲染实现原理。

star-history-in-github-readme 上图来自 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 嵌入:四步拿到可直接粘贴的代码

操作步骤

  1. 打开 Star History 主页并查询一个仓库;
  2. 点击图表下方的 Embed 按钮;
  3. 在弹窗中输入你自己的 GitHub 个人访问令牌(personal access token);
  4. 点击 Copy 按钮,将生成的代码粘贴到你的网站或博客中。

embed-chart-with-iframe 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 方案虽然好用,但有两个硬伤:

  1. GitHub 的 Markdown 渲染器禁止 <iframe> 标签,导致它无法放进仓库 README 展示在首页;
  2. 令牌安全:虽然 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

  1. 打开 Star History 主页并查询一个仓库;
  2. 向下滚动到操作按钮下方的嵌入区域;
  3. 点击 Copy 按钮;
  4. 将代码粘贴到仓库的 README 文件中。

embed-chart-with-svg 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 池 + 多层缓存"给出了可长期运行的生产级答案。

登录后查看全文
star-history