[🛠] 给 GitHub Pages 博客加上访客计数器

✨ GPT-5.5 的摘要 　

在静态 GitHub Pages 博客上接入免费额度内的 Cloudflare Worker 和 D1，保留既有 GA 累计值，同时显示今日访问数和单篇文章浏览量的记录。

我想给博客加一个访客计数器。

不是因为这个功能本身有多厉害。倒不如说正相反。它感觉像是一个太理所当然的功能，但用 GitHub Pages 做出来的静态博客里，并不会自然带着它。

Google Analytics 原本已经接好了。作为运营者，我进 GA 就能看到访问人数和浏览量。但那些不是显示在博客里的数字。访客看不到这个博客今天是否仍然有人在读，也看不到最近的文章大概被读了多少。

我想要的是像 Naver Blog 那样，今日、累计、单篇浏览量小小露出来的感觉。它与其说是拿来炫耀的数字，不如说更像一个信号：这个博客不是死掉的静态页面，而是还在持续被阅读。

所以问题很简单。

能不能保留免费静态博客的优点，同时只把访问统计这一小块做成动态的？

先定下条件

我不想只是为了加一个访客计数器，就把结构做大。

一开始我就定了几个条件。

• 保持 GitHub Pages 和 Jekyll 的写作流程。
• 不使用付费服务器。
• 不管是 Cloudflare 还是 Firebase，都要在免费额度内解决。
• 小小地放在个人资料附近。
• 在移动端也不要变得奇怪地过长。
• 不只显示博客整体统计，也显示单篇文章的浏览量。
• 不丢掉既有 GA 累计值。

最后一个条件尤其重要。

如果因为加了新计数器，浏览量就从 0 开始，会很奇怪。博客已经在运行了，GA 里也早就累积了过去的浏览量。可如果继续只读 GA，又和我想要的计数器感觉有距离。

我以为只读 GA 就能结束

一开始我以为读取 Google Analytics API 就可以了。

GA 已经有数据，所以我觉得只要让一个 Cloudflare Worker 调用 GA API 再返回数字就行。实际上我也创建了服务账号，给 GA 属性加了权限，API 调用也跑通了。

但真正接上去之后，它和我想要的东西不一样。

GA 是分析工具。它适合运营者事后看趋势，但要当作博客页面上立刻有反应的访客计数器，就有点微妙。尤其是 今日 这个数字有问题。我刚刚进过博客，今天的值却还显示 0，访客看到时只会觉得它坏了。

指标名称也容易混淆。active users 和 page views 是不同的值。如果严格按访问人数来抓，数字会显得过于保守；如果用 page view，体感上更自然，但命名就需要小心。

最后判断很简单。

GA 用作过去的基准值，从现在开始增加的计数则由我自己来抓。

把 baseline 和增量分开

最终结构是这样定的。

公开浏览量 = GA baseline + Cloudflare D1 增量

GA baseline 是此前已经累积的数字。先确定一个基准日，保存截至那一刻的全站浏览量和单篇文章浏览量。

从那之后，就由 Cloudflare Worker 直接计数。访客进入博客时，JavaScript 调用 Worker，Worker 再把今日、当月、全站、按 page path 区分的增量记录到 D1。

整理起来就是这样。

既有累计值: Google Analytics baseline
新增增量: Cloudflare Worker + D1
公开 API: Cloudflare Worker
博客显示: Jekyll include + JavaScript

我喜欢这个方式，是因为两边都没有丢掉。

GA 里既有的数据保留下来。同时，未来的计数也能在博客页面上立刻产生反应。

为什么是 Cloudflare Worker 和 D1

Firebase 也曾经是候选。但对这种规模的功能来说，Cloudflare 这边更简单。

GitHub Pages 是静态站点，没有地方放服务器代码。Worker 正好小小地填上这块空缺。D1 基于 SQLite，用来保存访客计数器这种简单数字已经足够了。

费用条件也合适。个人博客的访客计数器，这种程度可以在免费额度内处理。万一突然来了很多人，计数可能会有一些晃动，但文章本身不会坏掉。说到底，这也不是支付系统或财务账本。

我想要的不是精确会计，而是展示博客正在被阅读的流动感。

适度挡住 bot 和重复访问

给公开页面加上计数器之后，bot 也可能把数字加上去。

要完美挡住很难。而且挡得太严格，反而会离我想要的计数器感觉越来越远。我想要的是像 Naver Blog 那样，某种程度上略宽松地计数。

所以 Worker 里只处理了几件事。

• 排除明显的 bot user-agent。
• 同一个访客和同一个页面的组合，在一定时间内不重复计数。
• 单篇文章浏览量也用同样方式，按 path 累积增量。

也就是说，它不是严格的分析工具，而是按照公开访客计数器来调整的。

页面上只小小地放进去

一开始我想把统计拆成好几格来显示。但放在个人资料旁边的 UI 必须小。数字一多，博客首页反而会显得杂乱。

所以最后留下的是三个。

今日 / 本月 / 总计

今日 给人一种博客现在正在被阅读的感觉。本月 展示最近的规模感。总计 展示博客累积过来的时间。

文章列表里，我也给每篇文章加上了浏览量。

浏览量 10 次

这个值也和整体统计使用同样的结构。

单篇浏览量 = GA 单篇 baseline + Cloudflare D1 单篇增量

例如，某篇文章在 GA 基准下已经被浏览了 9 次，切换到新计数器之后又被读了 1 次，那么页面上就会显示 10 次。

这最自然。过去的浏览量不丢，未来的浏览量也会马上累积。

结果

结果，博客个人资料附近出现了这样的数字。

今日 1 / 本月 66 / 总计 4,944

文章列表里则会像这样显示浏览量。

浏览量 10 次

单看一个功能，它很小。但我挺喜欢这次工作。

问题很明确。GitHub Pages 博客没有访客计数器。GA 已经有了，但作为公开页面上的计数器还不够。可我也不想为了一个博客，就把服务器做得很大。

所以我把既有 GA 数据作为 baseline 保留下来，再用 Cloudflare Worker 和 D1 只直接计数之后的增量。

静态博客的优点仍然保留。用 Markdown 写文章，用 GitHub Pages 部署，维护成本几乎接近 0。只是把真正缺少的那一块，叠上了一个很小的 serverless 组件。

以后如果有机会把这个博客像作品集一样展示，这种工作反而应该很好说明。它不是夸张的大功能，但它从真实的不便出发，限制住成本和复杂度，并且最后接成了可以运营的形态。