GitHub 新 Star 历史接口能获取哪些统计数据

如果你的报表只关心“这个仓库最近增长得快不快”，GitHub 新增的 Star history REST API 已经给出了更合适的数据入口：它按日和按周返回 Star 数量变化，但不暴露每个 stargazer 的账号。换句话说，你可以继续画增长曲线、做周环比和识别发布后的峰值，却不能把它当成用户明细接口。

新接口到底返回哪些统计数据

GitHub 在 2026 年 9 月 4 日的 Changelog 中说明，新接口用于在不暴露 stargazer 身份的前提下追踪仓库 Star 增长。官方 REST 文档把返回结果定义为按日历周分组的历史序列，最近的一周排在前面。

官方示例中的一条记录形如 {"week":1754784000,"total":19,"days":[0,12,7,0,0,0,0]}。这里的 19 应当等于七个日值之和。这个接口给的是仓库层面的聚合统计，不包含登录名、用户 ID、头像或每次 Star 的个人时间戳。

一次请求如何读取周与日数据

公共仓库可以在不认证的情况下请求这类公开资源；需要认证时，细粒度令牌至少要有仓库 Metadata 读取权限。生产脚本仍建议显式带上推荐的 Accept 头和 API 版本头：

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  -H "Authorization: Bearer " \
  "https://api.github.com/repos/OWNER/REPO/stargazers/history?per_page=30&page=1"

拿到 JSON 后，先把 week 转成应用时区的日期，再保存 days[0]...days[6]。不要用当前仓库的 stargazers_count 去替换历史记录中的 total：前者是当前仍保留 Star 的用户数量，后者是某个日历周内新增的 Star 数，两者回答的是不同问题。

如果只要当前总量，原有的 GET /repos/{owner}/{repo}/stargazers/count 更直接；如果要趋势，才使用 /stargazers/history。把两个结果放到同一张图时，应在图例中明确“当前存量”和“周期新增”两个口径。

分页和时间边界怎么处理

历史接口每页最多 30 条，页码最多到 100。第 1 页是最近周，下一页继续向更早的周移动；同一页内仍是从新到旧。因此，拉完多页后应先按 week 升序排序，再交给图表或周环比计算。不能直接把响应数组首尾拼成最终趋势，否则折线会从今天倒着走。

文档还特别说明：没有新增 Star 的周也会返回 0，days 的七个位置从周日开始，而且周和日的边界不保证与 UTC 完全一致。对跨时区团队，建议把原始 week 和展示日期同时保存，避免用本地日期重新推算后出现一周偏移。

旧的 stargazers 列表脚本如何迁移

这次变化的关键不是换一个 URL，而是数据权限边界变了。GitHub 文档说明，stargazers 列表相关端点的访问已限制给管理员和协作者；新的 history 端点提供的是隐私安全的聚合替代方案。

迁移时可以按下面的判断处理：需要增长曲线，就改为读取 history；需要当前总量，就调用 count；需要“谁点了 Star”，则不能把 history 当作替代品，也不应继续围绕公开用户列表设计新的采集流程。已有内部工具还要检查分页上限、去重键和时区转换，尤其不要把 days 数组误读成从周一开始。

常见问题

history 接口能返回每个用户的 Star 时间吗？

不能。它只返回仓库在每个日历周和每天新增的数量，个人身份和个人事件时间不在返回模型里。

total 是这一周结束时的总 Star 数吗？

不是。total 表示该周新增数量；当前仍保留的 Star 总量应使用 stargazer count 或仓库当前元数据口径。

为什么图表的周一和 GitHub 数据对不上？

先检查两个地方：days 的第一个元素是周日，以及文档没有保证周边界与 UTC 对齐。保存原始时间戳并统一展示时区后再聚合。

这项更新让“Star 趋势分析”重新有了稳定的聚合入口，但它刻意没有恢复用户明细。对监控、发布复盘和项目热度报表而言，这通常已经够用；对身份级分析而言，则应重新审视需求是否真的需要这类数据。