GitHub Stats

一个用于拉取 GitHub 用户统计信息的 TypeScript 工具。

• Stars：用户拥有仓库的总星标数
• Commits：GitHub Contributions 中记录的提交贡献数
• Followers：关注者数量

特性

• 支持 stars、commits、followers 三类统计
• 优先使用 GraphQL 批量获取数据
• GraphQL 失败时自动降级到 REST/Search API
• 自动处理 GitHub API 分页
• 支持私有仓库 Commit Contribution 统计（需授权）
• 支持失败时使用自定义 fallback 文案

环境要求

• Node.js 18+
• GitHub Personal Access Token

配置

运行前需要设置环境变量 GITHUB_TOKEN。

如果仅统计公开数据，Fine-grained PAT 赋予 Public repositories 只读权限即可。

如果需要统计私有仓库的 Commit Contribution，则需要为相关私有仓库授予读取权限：

• Fine-grained PAT：授予目标私有仓库访问权限，并赋予 Contents（Read-only）权限
• Classic PAT：通常需要 repo 权限

需要注意：

• 私有仓库贡献数据只能通过 GraphQL 路径完整获取
• 当 GraphQL 不可用时，程序会自动回退到 Search API
• Search API 的统计口径与 GitHub Contributions 并不完全一致，因此 Commit 数量可能略有偏差
• 回退模式下不会统计私有仓库贡献

Windows CMD：

set GITHUB_TOKEN=your_github_token

PowerShell：

$env:GITHUB_TOKEN = "your_github_token"

Linux / macOS：

export GITHUB_TOKEN=your_github_token

使用

import { resolveGitHubStats } from './github-stats';

async function main() {
	const stats = await resolveGitHubStats({
		username: '5ime',
		fallbacks: {
			stars: 'N/A',
			commits: 'N/A',
			followers: 'N/A',
		},
	});

	console.log(stats);
}

main();

返回结果示例：

[
	{
		value: '1,234',
		label: 'Stars',
		description: 'GitHub 星标数统计',
	},
	{
		value: '567',
		label: 'Commits',
		description: 'Git 提交次数统计',
	},
	{
		value: '89',
		label: 'Followers',
		description: '关注者数量统计',
	},
];

导出 API

resolveGitHubStats(config)

参数：

参数	类型	说明
username	string	GitHub 用户名
fallbacks	Partial<Record<GitHubStatMetric, string>>	失败时使用的备用显示值

返回：

Promise<ResolvedStat[]>

类型定义

type GitHubStatMetric = 'stars' | 'commits' | 'followers';

interface ResolvedStat {
	value: string;
	label: string;
	description: string;
}

实现说明

Stars

通过 GitHub REST API 获取用户拥有的全部仓库，并统计其获得的 Stars 总数。

统计范围：

• 用户拥有（Owner）的仓库
• 不包含组织仓库
• 自动处理分页

Commits

优先通过 GitHub GraphQL API 获取 GitHub Contributions 中记录的 Commit Contribution 数量。

实现方式：

• 根据用户注册年份自动生成统计区间
• 按年份查询 Contribution 数据
• 汇总所有年份的 Commit Contribution

当 GraphQL 不可用时：

• 自动回退到 Search API
• 使用 author:<username> 进行近似统计
• 结果可能与 GitHub Contributions 页面显示的数据存在差异

Followers

直接读取 GitHub 用户资料中的 Followers 数量。

降级策略

程序会优先尝试通过 GraphQL 批量获取统计数据：

• Followers
• Commits
• Stars（仓库数量不超过 GraphQL 单页限制时）

如果 GraphQL 请求失败：

1. 自动回退到 REST API
2. 自动回退到 Search API（Commits）
3. 单项统计失败时使用对应 fallback 值