GitHub Readme Stats 停更之后：自托管还是换用继承者
:zap：为您的 github 自述文件动态生成统计信息。使用 &theme=THEME_NAME 参数，如下所示：所有内置主题 GitHub Readme Stats 都附带多个内置主题（例如
秒懂
- 它是什么？
- anuraghazra/github-readme-stats 曾是生成 README 统计卡片的主流方案，但仓库已声明不再维护。本文梳理它的工作机制、部署方式与替代路线，帮你决定是否还要继续使用。
- 适合谁用？
- 如果你只是想在个人主页放一张统计卡片，且能接受公共实例偶尔超时，那么继续用现有链接暂时无妨，但不要指望任何修复。若你依赖卡片展示私有仓库数据，或需要长期稳定服务，应尽快迁移到官方推荐的 GitHub Stats Extended，或改用 GitHub Readme Stats Action 在 CI 中生成静态图片。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 16 天前。
- 用什么语言写的？
- 主要是 JavaScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
一个曾经统治 README 的卡片生成器
GitHub Readme Stats 解决的是一个很具体的问题：GitHub 的 README 本身是静态 Markdown，无法直接嵌入动态数据。想在个人主页展示 star 数、提交数、常用语言，过去只能手动截图或写脚本。这个项目用一张图片 URL 解决了问题，你把链接贴进 README，服务端实时请求 GitHub API，生成 SVG 卡片返回。它面向的是 GitHub 个人资料页的维护者，尤其是想让主页看起来更专业的开发者。项目基于 JavaScript，MIT 许可，核心逻辑在服务端完成。但注意，仓库顶部现在有一条醒目的警告：这个仓库不再维护，官方推荐使用继承者 GitHub Stats Extended。这意味着你看到的文档虽然完整，但已经是冻结状态。
卡片类型与查询参数的实际用法
项目提供五种卡片：GitHub Stats Card 显示 star、commit、PR 等统计，Extra Pins 用于固定仓库，Gist Pins 展示 Gist，Top Languages Card 分析语言占比，WakaTime Card 展示编码时间。每种卡片都有独立的查询参数。比如 Stats Card 用 ?username= 指定用户，用 &hide= 隐藏某些统计项，用 &show_icons=true 显示图标。Top Languages Card 支持 &layout=compact 切换紧凑布局，还有 donut、pie 等变体。最常用的主题参数是 &theme=，内置多种配色。文档给出了具体示例，例如复制一行 Markdown 图片链接即可使用。值得注意的是，默认情况下统计卡片只显示公共仓库的数据，私有仓库的统计需要自托管并配置自己的 token。
排名算法：S 到 C 的评级机制
统计卡片里有一个容易被忽略的细节：它会给用户打一个 S 到 C 的等级。S 代表前 1%，A+ 是 12.5%，依次递减，C 覆盖所有人。这个评级参考了日本学术评分体系。算法不是简单排序，而是对提交数、PR 数、issue 数、star 数、关注者数分别计算百分位，再用指数分布和对数正态分布的累积分布函数做加权求和。具体实现放在 src/calculateRank.js 文件里。这个设计让评级相对平滑，不会因为某个指标极端而失控。但这也意味着评级依赖全局数据分布，公共实例的计算结果会随所有用户的数据变化而波动。如果你在意这个数字的稳定性，自托管时依然无法避免，因为算法本身是全局性的。
公共实例的可靠性问题与缓存机制
README 里明确警告：公共 Vercel 实例是 best-effort 状态，可能因为速率限制和流量高峰而不可靠。项目使用缓存来改善稳定性，文档里有 common options 一节说明缓存参数。但即便如此，官方仍然建议自托管或者用 GitHub Actions 生成卡片。这一点很关键：如果你把卡片链接直接指向公共实例，你的 README 可能偶尔加载失败。对于个人主页这种低风险场景，偶尔失败可以接受，但对于需要稳定展示的团队或项目，这就是硬伤。缓存机制能减轻 GitHub API 的调用压力，但无法消除公共实例的带宽瓶颈。
部署方式：Vercel 自托管还是 GitHub Actions
文档推荐两种自托管方式。第一种是部署到 Vercel 或其他平台，你需要先获取 Personal Access Token，设置环境变量，然后导入仓库。README 列出了可用的环境变量，但没有给出完整列表，需要看源码确认。第二种是 GitHub Actions，这个方式更轻量，在个人 profile 仓库里配置 workflow，让 CI 生成卡片并提交静态图片。这两种方式各有取舍：Vercel 部署保持动态生成，但你需要维护一个服务；Actions 方式生成静态文件，没有运行时依赖，但卡片内容不会实时更新，除非定期触发 workflow。文档提到有视频教程，但具体步骤在截断的 README 里没有完全展示。
维护状态：一个必须正视的停止信号
这个项目最突出的问题不是技术缺陷，而是维护状态。仓库顶部用 CAUTION 级别的警告声明不再维护，并指向两个替代品：GitHub Stats Extended 和 GitHub Readme Stats Action。前者是活跃维护的 fork，增加了新特性和稳定性改进，后者是 GitHub Action，用于在 CI 中生成卡片。原项目没有最近的 release 信息，最后推送时间未知，这进一步印证了停更状态。对使用者来说，这意味着安全漏洞不会修复，GitHub API 变化不会适配，新功能更不会出现。如果你已经在使用原项目，应该把迁移列入计划，而不是继续依赖。
替代方案的实际差异与迁移成本
官方推荐的两个替代品走的是不同路线。GitHub Stats Extended 是原项目的 fork，意味着它保留了原有 API 和查询参数，迁移成本最低。你大概率只需要把图片链接的域名从 github-readme-stats.vercel.app 换成新项目的地址，参数基本兼容。GitHub Readme Stats Action 则完全不同，它在 CI 中运行，把卡片作为静态图片提交到仓库，不依赖任何公共服务。这个方式更可靠，但需要你配置 workflow，并且卡片更新有延迟。另一个选择是继续自托管原项目，但既然上游已停更，这等于把维护责任揽到自己身上，除非你有明确理由，否则不值得。
谁该用，谁该走，以及先验证什么
如果你只是想在个人主页放一张卡片，不在乎偶尔加载失败，也不依赖私有数据，那么继续用现有链接是最省事的方案。但如果你把卡片放在简历、项目文档或团队页面里，可靠性就变得重要，这时候应该迁移到 GitHub Stats Extended 或 Actions 方案。迁移前需要验证三件事：一是你使用的所有查询参数在新项目中是否仍然支持，尤其是 theme、hide、rank_icon 这类自定义项；二是私有仓库的统计是否需要配置新 token；三是 Actions 方案的 workflow 文件是否与你的仓库结构兼容。原项目的 MIT 许可允许自由使用和修改，但既然官方已经指明了方向，跟着走比另起炉灶更实际。
编辑结论
如果你只是想在个人主页放一张统计卡片，且能接受公共实例偶尔超时，那么继续用现有链接暂时无妨，但不要指望任何修复。若你依赖卡片展示私有仓库数据，或需要长期稳定服务，应尽快迁移到官方推荐的 GitHub Stats Extended，或改用 GitHub Readme Stats Action 在 CI 中生成静态图片。迁移前先确认你使用的查询参数在新项目中是否仍然有效，尤其是 theme、hide、rank_icon 这类自定义选项。自托管原项目虽然可行，但既然上游已明确停止维护，把新代码建立在死分支上不是明智选择。
社区笔记