GitHub Star History 使用指南:从仓库搜索、多仓对比到 README 实时图表嵌入

原创2026-10-06 20:22:311,425 阅读
文章标签:开发工具数据可视化

GitHub Star History 使用指南:从仓库搜索、多仓对比到 README 实时图表嵌入

GitHub Star 数量是衡量开源项目最直观的指标,但一个「当前很火」的仓库,究竟是持续增长、还是已经停滞甚至走下坡路,仅凭一个静态数字无从判断。本文以 Star History)为对象,完整讲解从搜索仓库、多仓对比、时间轴对齐,到配置 GitHub Token 解除 API 限流、把实时 Star 历史图表嵌入 README 的每一步操作,并补充前端源码级的实现细节,让你看完即可上手。

为什么不能只看 Star 总数

当你评估一个开源工具时,通常会问自己几个问题:还有没有别的用户在用它?它在同类中是不是最受欢迎的?这项技术是不是在走下坡路?答案都可以从一个维度获得线索——GitHub Stars。

但 Star 总数本身有很强的「幸存者偏差」:一个项目今天拥有海量 Star,不代表它仍在高速增长或持续维护;反之,一个项目可能经历过爆发式增长后已进入平台期。只看当前数字,你无法判断它处在增长曲线的哪个位置。Star History 的价值正在于此:它把仓库的 Star 数量随时间的变化完整画出来,让你一眼看清项目「是正在上升、平稳运行、还是正在衰退」。该项目本身免费且开源(可在 git clone https://gitcode.com/gh_mirrors/st/star-history 获取源码)。

界面总览:极简设计下的完整能力

Star History 首页使用手册

Star History 首页就是一个简单的搜索框,这是它贯彻始终的第一设计原则。但在简洁的外表下,它为进阶用户准备了相当完整的能力集,本文接下来会逐一演示:

  • 用 3 种不同格式添加仓库;
  • 添加多个仓库进行同图对比;
  • 对齐时间轴以公平比较不同「年龄」的仓库;
  • 在图表中临时显示 / 隐藏某个仓库;
  • 添加 GitHub Personal Access Token 以解除 API 调用限制;
  • 把实时 Star 历史图表嵌入 GitHub 项目 README;
  • 通过 Chrome 扩展在浏览任意仓库时随手查看其 Star 历史。

从源码结构看,这些能力分别由 RepoInputer.tsx(输入与仓库列表管理)、StarChartViewer.tsx(图表渲染与工具栏)、TokenSettingDialog.tsx(Token 配置)和 GenerateEmbedCodeDialog.tsx(嵌入代码生成)协作实现,下文将结合这些实现逐项展开。

添加仓库:支持 3 种输入格式

Star History 搜索框

添加仓库非常简单,直接在搜索框输入即可,以下 3 种格式都有效:

  1. 粘贴完整 URL:例如 https://github.com/star-history/star-history;
  2. 省略前缀:懒得敲完整地址时,可以只写 star-history/star-history,即省去 https://github.com/ 部分;
  3. 仓库名与组织名一致时只需写一次:例如 star-history 本身就是 star-history/star-history;但像 hashicorp/terraform 这种「组织名 ≠ 仓库名」的情况,写 hashicorp 或 terraform 都无法匹配,必须完整指定 hashicorp/terraform。

这个解析逻辑在源码中有明确的实现依据。RepoInputer.tsx 中通过正则 GITHUB_REPO_URL_REG = /github.com\/(\S*?\/\S*)/(定义见 helpers/consts.tsx)识别完整 URL;随后按 / 切分:只有一段时自动补成 owner/repo,两段及以上时取前两段,从而把任意合法输入归一化为 owner/repo 形式。输入框还支持回车确认与「粘贴自动清理空白」等细节,搜索结果会通过 URL Hash 同步到浏览器地址栏(详见下文「进阶小技巧」)。

添加多个仓库:同图对比增长趋势

添加第一个仓库后,继续在输入框中输入下一个仓库即可,所有仓库会渲染在同一张图上,方便直观对比。

多仓库对比

例如,当你纠结数据库变更管理工具该选谁时,可以把 Flyway 和 Liquibase 放进同一张图:两者都起步很早、多年持续增长;但近几年 Bytebase 增长明显加快,已反超 Liquibase。仅凭 Star 总数很难得出这个结论,而叠加了时间维度的曲线能清晰揭示「谁在加速、谁在放缓」。需要提醒的是:Star 数与曲线走势只是「值得关注」的线索,不能作为选择的唯一依据,实际选型还应结合功能、维护活跃度与社区生态综合判断。

对齐时间轴:公平比较不同「年龄」的仓库

不同仓库的创建时间不同,直接对比绝对时间轴对「年轻」项目并不公平。勾选 Align timeline(对齐时间轴)后,图表会重绘:所有仓库曲线的起点被对齐到各自诞生的第一天,从而让你直接比较「各自发布 N 个月后」的表现。

对齐时间轴后的对比图

在实现上,这一开关对应图表模式 Timeline(相对时间)与 Date(绝对日期)的切换,见 StarChartViewer.tsx 中的 handleToggleChartBtnClick;模式会同步进 URL Hash(如 type=timeline),由 store/index.tsx 在页面加载时解析并还原图表状态。同区域的 Log scale(对数刻度)开关也值得一试——当对比对象的 Star 量级相差悬殊时,对数刻度能放大「小仓库」的增长斜率,避免小曲线被压平。

临时显示 / 隐藏仓库:无需删除即可聚焦

当图上有多个仓库时,你不需要删除某个仓库来减少干扰——直接点击图例(label box)中对应的仓库名称,即可切换其显示 / 隐藏状态;被隐藏的仓库名会带删除线标识,再次点击即可恢复。

对应实现是 RepoInputer.tsx 中的 handleToggleRepoItemVisible:它仅切换该仓库的 visible 状态而不移除数据,并将不可见仓库从 store.repos 中过滤,图表随即按可见集合重绘;只有所有仓库都被隐藏时,图表本身才会隐藏。

配置 GitHub Token:解除 API 调用限制

Star History 免费使用,但它需要调用 GitHub API 获取仓库元数据与 Star 时间序列,因此你最好提供一个 GitHub Personal Access Token 来解除 API 限流。整个过程不需要任何个人数据,权限上仅需只读的 repo 范围。

添加 Access Token 入口

配置步骤:

  1. 登录 GitHub 账号,进入 Settings → Developer settings → Personal access tokens 页面;
  2. 点击 Generate new token;
  3. 选择 Generate new token (classic)(经典令牌);
  4. 在令牌详情页填写表单:
    • Note:给令牌起个便于识别的名字;
    • Expiration:设置有效期,到期后需重新生成;
    • Select scopes:令牌的权限边界,对 Star History 来说勾选 repo 即可;
    • 填写完成后点击页面底部的 Generate token;
  5. 务必立刻复制生成的令牌——它只会展示这一次,关闭页面后就再也看不到了;
  6. 回到 Star History 首页,点击 Edit Access Token,粘贴令牌并点击 Save。之后即使令牌过期,也仍是在同一入口重新编辑。

从实现看,Token 会被保存在浏览器 localStorage 的 accessTokenCache 键中(见 helpers/storage.tsx 与 TokenSettingDialog.tsx),之后所有 GitHub API 请求都会在 Authorization: token <token> 头中带上它(见 shared/common/api.tsx)。注意:令牌保存在本地存储,属于浏览器本地数据,请勿在公共设备上使用该功能。另外,TokenSettingDialog.tsx 会在请求返回 401/403(限流或未授权)时自动弹出配置窗口,提示你补充令牌。

把实时 Star 历史图表嵌入 GitHub README

这是 Star History 最常用的场景:把一张实时更新的图表放进项目 README,读者打开页面即可看到最新曲线。有两种嵌入方式:

方式一:iframe 嵌入(Live Chart)

  1. 在图表下方点击 Embed 按钮;
  2. 首次使用需先填入你的 Personal Access Token(与上一节同一个令牌);
  3. 复制生成的 iframe 片段,粘贴进 README 即可。

生成逻辑见 GenerateEmbedCodeDialog.tsx:它会读取当前图中的仓库列表、图表模式(type=date / type=timeline)、对数刻度(logscale)与图例位置(legend=top-left / bottom-right)等状态,拼出形如下面的 iframe:

<iframe
  style="width:100%;height:auto;min-width:600px;min-height:400px;"
  src="https://star-history.com/embed?secret=<你的令牌>&#star-history/star-history&type=date&legend=top-left"
  frameBorder="0"
></iframe>

其中 secret 参数是令牌的 Base64 编码(代码中通过 btoa(token) 生成),用于服务端校验。粘贴后,你的 README 里就会出现一张与 Star History 网站实时同步的 Star 曲线。

方式二:Markdown + SVG 图片嵌入(Badge 式图表)

除了 iframe,前端还内置了另一种更轻量的嵌入方式:在图表下方的 Markdown 区块(实现见 EmbedMarkdownSection.tsx)点击「Copy to GitHub README.md」,即可复制一段 Markdown 代码,其本质是引用后端生成的 SVG 图片接口:

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=star-history/star-history&type=date&legend=top-left)](https://star-history.com)

对应地还提供「dark theme supported」的深色主题变体(通过 <picture> 标签按 prefers-color-scheme 自动切换,参数中追加 theme=dark)。后端生成 SVG 的实现位于 backend/og-card.ts 等文件中,前端项目自身的 README(README.md)顶部就嵌入了这样一张实时图表,可作为现成示例。

Chrome 扩展:浏览仓库时随手查看

除了网站本体,Star History 还提供免费的 Chrome 扩展:

  1. 在 Chrome Web Store 搜索并安装 Star History 扩展;
  2. 打开任意 GitHub 仓库页面,点击浏览器工具栏中的扩展图标,页面上即会出现一个悬浮的 Star 历史图表小窗口,无需离开当前页面即可查看该仓库的增长曲线。

从项目结构看,扩展与主站共用前端代码,可通过 cd frontend && pnpm build:ext 构建(构建配置见 frontend/package.json 与 plugins/scripts/copyExtensionFiles.ts),再将生成的 ./dist 目录作为「已解压的扩展程序」加载到 Chrome 扩展管理页。

进阶小技巧:用 URL 直接分享 / 复现图表状态

聊完官方手册的七个操作,再补充一个源码里能看到、对分享场景非常实用的机制:图表的所有状态都会同步到 URL Hash 中。RepoInputer.tsx 会在仓库列表、图表模式等变化时写回 location.hash,格式为:

#owner/repo1&owner/repo2&type=date&logscale&legend=top-left

反过来,store/index.tsx 在页面加载与 hash 变化时解析这些参数并还原完整图表状态。也就是说,你可以把带 Hash 的页面链接直接发给别人——对方打开即看到同一组仓库、同一模式与同一样式,无需重新配置。这也正是 README 顶部实时图表示例(README.md)使用 https://star-history.com/?repos=... 形式分享图表的底层原理。

小结

总结一下 Star History 的核心用法:三种格式输入仓库、多仓同图对比、对齐时间轴公平比较、点击图例临时显隐、配置 Token 解除限流、iframe 或 SVG 两种方式嵌入 README,外加 Chrome 扩展随开随看。掌握这些操作后,无论是评估第三方开源项目,还是给自己的仓库 README 挂一张实时增长曲线,都能在几分钟内完成。如果你想在本地运行本项目体验全部功能,可按 README.md 中的指引:cd frontend && pnpm i && pnpm dev 启动主页(默认 http://localhost:3000),cd backend && pnpm i && pnpm dev 启动用于生成 SVG 图表的 API 服务(默认 http://localhost:8080)。

登录后查看全文
star-history