GitHub今日热榜系统搭建：从抓取到展示的完整实践

1. 从“今日热榜”看开源风向：这个项目到底在解决什么问题

第一次听说“Github今日热榜”这个概念，是在一个开发者群里。有人甩了张截图，上面列着当天涨星最快的十个仓库，配文是“今天的快乐源泉来了”。我当时的第一反应是：这东西不就是个排行榜吗，能有多大价值？后来自己动手搭了一套，用了一段时间才发现，它解决的是一个非常具体的痛点——信息过载下的高效筛选。

Github 上目前有超过四亿个仓库，每天新增的项目数以万计。你不可能一个个翻，Trending 页面虽然官方有，但更新频率、排序逻辑、语言筛选这些维度对国内开发者来说并不总是顺手。更关键的是，很多人打开 Github 是有明确目的的——找工具、找轮子、找灵感，而不是漫无目的地逛。这时候一个聚合了“今日涨星最快”“本周新晋热门”“特定语言趋势”的榜单，价值就出来了。

这个项目适合谁？三类人。第一类是技术选型者，需要快速判断某个方向最近有没有靠谱的新方案冒出来；第二类是内容创作者，需要追踪热点找选题；第三类是学习者，想看看大家都在关注什么，避免闭门造车。不管你属于哪一类，核心诉求都是一样的：用最少的时间，拿到最值得看的那几个仓库。

我搭建的这套“Github今日热榜”系统，本质上是一个定时抓取 + 数据清洗 + 榜单生成 + 多端展示的小型数据管道。它不复杂，但涉及到的环节不少，每个环节都有坑。下面我会把整个设计思路、技术选型、实操步骤、踩过的坑全部拆开讲，你照着做就能跑起来。

2. 整体架构设计与技术选型背后的取舍

2.1 为什么不用官方 API 而选择页面解析

Github 官方提供了 REST API 和 GraphQL API，理论上你可以通过search/repositories接口配合sort=stars和created:>日期来获取数据。我一开始也是这么做的，但很快发现了三个问题。

第一，API 有速率限制。未认证请求每小时 60 次，认证后 5000 次。如果你要抓多个语言、多个时间维度的榜单，这个额度很快就会耗尽。第二，搜索结果有延迟。官方 API 的索引更新不是实时的，有时候一个仓库已经涨了几百星，API 里还是旧数据。第三，排序逻辑不透明。你无法精确控制“今日热榜”的算法，只能用它给的排序方式。

所以最终我选择了页面解析的方案。Github Trending 页面本身是服务端渲染的，结构相对稳定，解析起来并不复杂。而且它天然支持按语言、按时间范围筛选，省去了自己写筛选逻辑的麻烦。当然，页面解析也有风险——Github 改版会导致解析规则失效。我的应对策略是把解析规则做成可配置的，一旦页面结构变化，改配置就行，不用动核心代码。

提示：页面解析仅用于个人学习和技术研究，请控制请求频率，避免对目标站点造成不必要的压力。建议设置合理的抓取间隔，比如每 30 分钟一次。

2.2 数据存储：为什么选了 SQLite 而不是 MySQL

这个项目的数据量其实很小。每天抓取一次，每次几百条记录，一年下来也就十万条左右。这种量级用 SQLite 完全足够，而且部署简单，不需要额外维护数据库服务。我用的是better-sqlite3这个 Node.js 库，同步 API 写起来很顺手，性能也够用。

表结构设计上，我建了两张表。一张是repositories，存仓库的基本信息，包括full_name、description、language、stars、forks等字段，用full_name作为唯一索引。另一张是trending_records，存每次抓取的快照，包括repo_id、trending_date、rank、stars_gained等字段。这样设计的好处是，我既能查某个仓库的历史趋势，也能查某一天的热榜快照。

CREATE TABLE repositories ( id INTEGER PRIMARY KEY AUTOINCREMENT, full_name TEXT UNIQUE NOT NULL, description TEXT, language TEXT, stars INTEGER DEFAULT 0, forks INTEGER DEFAULT 0, created_at TEXT, updated_at TEXT ); CREATE TABLE trending_records ( id INTEGER PRIMARY KEY AUTOINCREMENT, repo_id INTEGER NOT NULL, trending_date TEXT NOT NULL, rank INTEGER, stars_gained INTEGER, period TEXT, language_filter TEXT, FOREIGN KEY (repo_id) REFERENCES repositories(id) );

2.3 展示层：静态生成 + 定时刷新

展示层我选择了静态页面生成的方案。每次抓取完成后，用模板引擎生成 HTML 文件，直接部署到静态托管服务上。这样做的好处是访问速度快、成本低、不需要维护服务器。页面上的数据通过 JavaScript 从 JSON 文件里加载，支持按语言、按时间范围筛选。

如果你想要更动态的体验，也可以做成服务端渲染的 Web 应用。但我个人觉得，热榜这种东西本来就是定时更新的，静态页面完全够用，而且更稳定。我用的模板引擎是EJS，简单直接，学习成本低。

3. 核心抓取逻辑与数据清洗的实操细节

3.1 抓取频率与请求头设置

抓取频率是个需要权衡的问题。太频繁了容易被限流，太稀疏了榜单更新不及时。我的经验是每 30 分钟抓一次比较合适。Github Trending 页面的数据本身也不是实时更新的，大概每小时刷新一次，所以 30 分钟的间隔足够覆盖。

请求头方面，最重要的是User-Agent。不要用默认的爬虫标识，建议设置成一个常见的浏览器 UA。另外，Accept-Language设置为en-US,en;q=0.9可以确保拿到英文页面，解析规则更稳定。

const headers = { 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36', 'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8', 'Accept-Language': 'en-US,en;q=0.9', };

3.2 页面解析的关键选择器

Github Trending 页面的结构这几年改过几次，但核心的article.Box-row这个选择器一直没变。每个仓库对应一个article元素，里面包含了仓库名、描述、语言、星数、今日涨星数等信息。

解析的时候有几个细节需要注意。第一，仓库名是相对链接，需要拼接https://github.com前缀。第二，今日涨星数的格式不固定，有时候是1,234 stars today，有时候是1,234 stars this week，需要根据时间范围做不同的正则匹配。第三，描述可能为空，要做好空值处理。

const cheerio = require('cheerio'); function parseTrendingPage(html, period = 'daily') { const $ = cheerio.load(html); const repos = []; $('article.Box-row').each((index, element) => { const $el = $(element); const fullName = $el.find('h2 a').attr('href').replace(/^\//, ''); const description = $el.find('p').text().trim() || ''; const language = $el.find('[itemprop="programmingLanguage"]').text().trim() || 'Unknown'; const starsText = $el.find('a[href$="/stargazers"]').text().trim().replace(/,/g, ''); const stars = parseInt(starsText, 10) || 0; const starsTodayText = $el.find('span.d-inline-block.float-sm-right').text().trim(); const starsGainedMatch = starsTodayText.match(/([\d,]+)\s+stars?\s+(today|this week|this month)/); const starsGained = starsGainedMatch ? parseInt(starsGainedMatch[1].replace(/,/g, ''), 10) : 0; repos.push({ fullName, description, language, stars, starsGained, rank: index + 1, }); }); return repos; }

3.3 数据去重与增量更新

每次抓取都会拿到一批数据，但并不是所有仓库都是新的。我的策略是先查后插：对于repositories表，如果full_name已存在，就更新stars和forks字段；如果不存在，就插入新记录。对于trending_records表，每次抓取都插入新记录，因为这是快照数据，需要保留历史。

这里有个坑要注意：SQLite 的 UPSERT 语法在不同版本里支持程度不一样。我一开始用的是INSERT OR REPLACE，但这样会改变id，导致外键关联出问题。后来改用了INSERT ... ON CONFLICT(full_name) DO UPDATE SET ...的写法，才解决了这个问题。

INSERT INTO repositories (full_name, description, language, stars, forks, updated_at) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(full_name) DO UPDATE SET description = excluded.description, language = excluded.language, stars = excluded.stars, forks = excluded.forks, updated_at = excluded.updated_at;

3.4 多语言榜单的抓取策略

Github Trending 支持按语言筛选，URL 格式是https://github.com/trending/{language}?since={period}。我常用的语言有 JavaScript、Python、Go、Rust、TypeScript 这几个。抓取的时候，我会遍历这些语言，分别抓取日榜和周榜。

这里有个效率问题：如果串行抓取，每个请求间隔 2 秒，六个语言两个周期就是 24 秒。虽然不算慢，但可以优化。我的做法是用Promise.all并发抓取，但把并发数控制在 3 以内，避免触发限流。实测下来，这样能把总时间压缩到 10 秒左右。

注意：并发抓取时一定要设置超时和重试机制。我遇到过某次请求卡住导致整个流程挂起的情况，后来加了AbortController和 3 次重试才稳定下来。

4. 榜单生成逻辑与展示层的实现

4.1 热榜排序算法的设计

“今日热榜”的核心是排序。Github 官方的 Trending 排序算法没有公开，但根据观察，它主要考虑的是单位时间内的星数增长，而不是总星数。一个总星数十万的仓库，今天涨了五十星，可能排在一个总星数千的仓库后面，因为后者今天涨了五百星。

我的排序逻辑参考了这个思路，但做了一些调整。我用的公式是：

score = stars_gained * 0.7 + stars * 0.3

这个公式的意思是，涨星数占 70% 权重，总星数占 30% 权重。这样既能突出新晋热门项目，又不会让老牌项目完全消失。当然，这个权重是可以调的，你可以根据自己的偏好修改。

另外，我还加了一个语言多样性的约束。如果前十里某个语言占了五个以上，我会把多出来的位置让给其他语言。这样做是为了避免榜单被单一语言霸占，让读者看到更全面的技术趋势。

4.2 静态页面的生成与部署

页面生成我用的是 EJS 模板。模板文件里定义了 HTML 结构，数据通过render方法注入。生成的页面包括首页、语言筛选页、详情页三种。

首页展示当日综合热榜，语言筛选页展示特定语言的热榜，详情页展示某个仓库的历史趋势。详情页的数据来自trending_records表，我会把某个仓库过去 30 天的涨星数据查出来，用简单的 SVG 折线图展示。

const ejs = require('ejs'); const fs = require('fs'); async function generateHomePage(repos, date) { const template = fs.readFileSync('./templates/home.ejs', 'utf-8'); const html = ejs.render(template, { repos, date }); fs.writeFileSync('./dist/index.html', html); }

部署方面，我用的是静态托管服务，把dist目录整个上传就行。如果你有自己的服务器，用 Nginx 托管也可以。关键是设置好缓存策略，HTML 文件不缓存，JSON 数据文件缓存 5 分钟，这样既能保证数据新鲜度，又能减少请求压力。

4.3 数据可视化的小技巧

详情页的折线图我没有用图表库，而是手写了一个简单的 SVG 生成函数。这样做的好处是页面体积小、加载快，而且完全可控。折线图的核心逻辑是：把涨星数据映射到 SVG 的坐标空间，然后用polyline元素画线。

function generateSparkline(data, width = 200, height = 50) { const max = Math.max(...data.map(d => d.starsGained)); const points = data.map((d, i) => { const x = (i / (data.length - 1)) * width; const y = height - (d.starsGained / max) * height; return `${x},${y}`; }).join(' '); return `<svg width="${width}" height="${height}"><polyline points="${points}" fill="none" stroke="#0366d6" stroke-width="2"/></svg>`; }

这个 sparkline 虽然简单，但信息量足够。读者一眼就能看出某个仓库的涨星趋势是上升、下降还是平稳。如果你想要更复杂的图表，可以引入 Chart.js 或 ECharts，但我觉得对于热榜场景来说，简单直接更重要。

5. 常见问题排查与避坑经验实录

5.1 抓取失败的各种原因与应对

抓取失败是最常见的问题，原因五花八门。我整理了一个排查表，按出现频率排序：

其中最常见的是 429 限流。我的应对策略是指数退避重试：第一次失败等 5 秒，第二次等 15 秒，第三次等 45 秒。如果三次都失败，就跳过这次抓取，记录日志，等下一个周期再试。

5.2 数据不一致的排查思路

有时候你会发现，同一个仓库在日榜和周榜里的涨星数对不上。这不是 bug，而是因为统计周期不同。日榜统计的是过去 24 小时，周榜统计的是过去 7 天。如果你要对比，一定要确保周期一致。

另一个常见问题是星数回退。偶尔会出现某个仓库的星数比上次抓取时还少的情况。这通常是因为 Github 清理了异常账号的星标，或者仓库被删除了部分星标。遇到这种情况，我的做法是保留最新数据，但在日志里标记出来，方便后续分析。

5.3 性能优化与资源控制

这个项目本身不重，但如果抓取的语言多、周期多，内存占用会上升。我做过一次测试，抓取 10 个语言、2 个周期，总共 20 个页面，内存峰值大概在 200MB 左右。对于一台 1GB 内存的服务器来说，完全够用。

如果你想要进一步优化，可以从这几个方面入手。第一，流式解析，不要一次性把整个 HTML 加载到内存里，用cheerio的流式接口。第二，增量更新，只抓取有变化的语言和周期。第三，数据压缩，历史快照数据可以按月归档，减少查询压力。

提示：如果你的服务器内存有限，建议把抓取任务拆分成多个小任务，用队列串行执行，避免并发过高导致内存溢出。

5.4 页面改版的应急处理

Github 改版是最大的风险。我经历过一次改版，article.Box-row变成了div.Box-row，导致解析全部失败。当时的应急处理是：先手动访问页面，用开发者工具找到新的选择器，然后更新配置文件，重启服务。整个过程大概花了 15 分钟。

为了减少改版带来的影响，我做了两件事。第一，把选择器抽成配置文件，改版时只需要改配置，不用动代码。第二，加了监控告警，如果连续三次抓取结果为空，就发邮件通知我。这样即使改版发生在半夜，我也能第一时间知道。

const selectors = { repoItem: 'article.Box-row', repoName: 'h2 a', description: 'p', language: '[itemprop="programmingLanguage"]', stars: 'a[href$="/stargazers"]', starsToday: 'span.d-inline-block.float-sm-right', };

这套配置化的思路，后来在我抓取其他网站时也复用了，效果很好。核心思想就是：把易变的部分和稳定的部分分开，易变的部分做成配置，稳定的部分做成代码。

6. 从热榜数据里能读出什么：几个真实的观察案例

6.1 语言趋势的周期性波动

我连续记录了三个月的热榜数据，发现了一个有趣的规律：Rust 和 Go 的涨星高峰通常出现在周中，而 JavaScript 和 Python 的高峰出现在周末。我的猜测是，周中是专业开发者的活跃时间，他们更关注系统级语言；周末是学习者的活跃时间，他们更关注应用级语言。

这个观察对我的选题帮助很大。如果我要写一篇面向初学者的文章，我会选在周末发布，配合 JavaScript 或 Python 的热榜项目。如果我要写一篇面向资深开发者的文章，我会选在周中发布，配合 Rust 或 Go 的项目。

6.2 新晋热门项目的共同特征

我分析了过去半年涨星最快的五十个项目，发现它们有一些共同特征。第一，解决了一个具体的痛点，而不是泛泛的工具。第二，README 写得非常清晰，有动图、有快速开始、有示例代码。第三，有活跃的社区，issue 回复快，PR 合并及时。

这些特征反过来指导了我自己的项目。我现在写 README 的时候，会刻意模仿那些热门项目的结构：先放一张动图展示效果，然后是三行快速开始，最后是详细的配置说明。实测下来，这样写的 README 确实能带来更多的 star。

6.3 热榜数据的局限性

热榜数据虽然有用，但也要注意它的局限性。星数不等于质量，有些项目靠营销手段刷星，实际代码质量堪忧。热榜有滞后性，一个项目从开始涨星到进入热榜，通常需要几天时间。热榜有偏见，英文项目更容易上榜，中文项目相对吃亏。

所以我的建议是：把热榜当作发现新项目的入口，而不是判断项目好坏的唯一标准。看到一个感兴趣的项目，还是要自己点进去看看代码、看看 issue、看看最近的提交记录，再做判断。

7. 后续可以扩展的几个方向

这套系统跑了一段时间后，我陆续加了一些小功能，也规划了一些大功能。已经加上的包括：邮件订阅，每天早上八点把当日热榜发到邮箱；RSS 输出，方便用阅读器订阅；API 接口，返回 JSON 格式的榜单数据，方便其他程序调用。

规划中的功能有两个方向。一个是个性化推荐，根据用户的历史浏览记录，推荐可能感兴趣的项目。另一个是趋势预测，用简单的时序模型预测某个项目未来一周的涨星趋势。这两个功能都需要更多的数据和更复杂的算法，目前还在实验阶段。

如果你也想搭一套类似的系统，我的建议是先从最简单的版本开始。不要一上来就搞分布式、搞机器学习，先把抓取、存储、展示这三个环节跑通，然后再逐步优化。我见过太多人一开始就想做完美，结果卡在某个细节上，最后不了了之。先跑起来，再迭代，这是最务实的做法。

最后分享一个小技巧：抓取的时候，把原始 HTML 也存一份到本地。这样即使解析规则出了问题，你也不用重新抓取，直接用本地文件调试就行。这个习惯帮我省了很多时间，尤其是在调试正则表达式的时候。