如果你也在用 Hexo + Butterfly,想给博客加一个「最近访客」能力,可以按本文一步步做。做完后会有:
- 侧栏「最近访客」卡片
- 独立页面
/visitor/ - 数据存在 Cloudflare(Worker + D1),免费额度对个人博客通常够用
本文按零基础可读来写:能注册 Cloudflare、会改博客配置即可。全程可用网页操作,不必装 Wrangler 命令行。文末附有完整可复制代码,不依赖作者仓库;示例里的 Database ID、Worker 域名都是假数据,请换成你自己的。
效果说明
- 读者打开你的博客时,页面会静默「打卡」一次(短时间重复刷新一般不会刷很多条)
- 首页等页面的侧栏显示大致地区、访问路径、相对时间
- 导航可进入
/visitor/查看更多 - 不展示完整 IP;默认在文章页不显示该侧栏卡(打卡仍会进行)
原理
三块积木:
- 博客前端 JS:告诉接口「当前打开的是哪一页」,并把列表画到侧栏
- Cloudflare Worker:小接口程序(打卡写入、查询列表)
- Cloudflare D1:SQLite 数据库,存访客记录
1 | 读者打开博客页面 |
body 只传 path:当前路径只有浏览器知道;IP / 地区 / UA 由 Worker 从请求读取,更准也不易伪造。
GitHub Pages / Netlify 只会部署静态博客,不会自动部署 Worker。接口要在 Cloudflare 控制台单独部署;你本地可把
visitor-api/当作源码备份目录。
你需要准备什么
- 已能跑起来的 Hexo + Butterfly 博客(本地
hexo server可打开) - Cloudflare 账号(邮箱注册即可,个人场景通常不必绑卡)
- 按文末附录在博客里建好对应文件(复制粘贴即可)
注册并进入 Cloudflare
- 打开 https://dash.cloudflare.com ,注册 / 登录。
- 左侧找到 「Workers 和 Pages」(Workers & Pages)。
- 第一次用可能会提示开通 Workers,按提示同意即可。
创建 D1 数据库
新建库
- 左侧进入 Workers 和 Pages。
- 打开 D1(在「存储和数据库」或 Workers 相关入口下)。
- 点 Create database / 创建数据库。
- 名称填:
blog-visitors(可自定,后面要一致)。 - 数据位置:选「位置」→ 亚太;不要勾「指定管辖权地」。
- 点 创建。
建表
- 点进库
blog-visitors→ Console(查询)。 - 粘贴并执行:
1 | CREATE TABLE IF NOT EXISTS visits ( |
- 再执行:
1 | SELECT name FROM sqlite_master WHERE type='table'; |
能看到 visits 即可。
库名和 Database ID 用在哪
在库的详情页可以看到 Database ID(UUID)。
示例(假数据):
- 库名:
blog-visitors - Database ID:
00000000-0000-4000-8000-000000000000
| 字段 | 用在什么地方 |
|---|---|
| 库名 | 网页绑定 Worker 时下拉选择;wrangler.toml 的 database_name |
| Database ID | 写在 wrangler.toml 的 database_id,给 CLI 部署用。网页绑定一般点选库名即可,仍建议记下 ID |
可选自测:
1 | INSERT INTO visits (visited_at, path, country, region, city, ua_brief, ip_hash) |
创建并部署 Worker
创建 Hello World
- Workers 和 Pages → 创建 → 从 Hello World! 开始(不要选 GitHub / 上传静态文件)。
- Worker 名称:
blog-visitors-api。 - 「使用 Cloudflare Access 保护」保持关闭。
- 点 部署。
记下地址,形如(假):https://blog-visitors-api.example.workers.dev(不要末尾 /)。
粘贴正式代码
- 进入该 Worker → Edit code / 编辑代码。
- 删掉默认代码,粘贴文末附录 「Worker:index.js」 全文。
- 把文件开头的
ALLOWED_ORIGINS改成你自己的博客域名(必须包含本地调试用的 localhost):
1 | const ALLOWED_ORIGINS = [ |
- Save and deploy。
绑定 D1
- Worker → Settings → Bindings → Add → D1 database。
- Variable name 必须填:
DB。 - Database 下拉选:
blog-visitors。 - 保存后再 Deploy 一次。
验证
浏览器打开:
https://blog-visitors-api.example.workers.dev/visits?limit=5
应返回类似 {"visits":[]} 或带数据的 JSON。若报 DB binding missing,检查绑定名是否为 DB 并重新部署。
接到你的 Hexo 博客
下面默认你的博客根目录里有 _config.yml、_config.butterfly.yml、source/ 等常见结构。
请新建这些路径,内容从文末「完整代码」整段复制(路径层级要一致):
| 路径 | 说明 |
|---|---|
visitor-api/src/index.js |
与 Cloudflare 里粘贴的 Worker 代码保持一致(方便以后改) |
visitor-api/wrangler.toml |
可选;把 database_id 换成你的 UUID |
source/self/visitor.js |
浏览器打卡与渲染 |
source/self/visitor.css |
样式 |
source/visitor/index.md |
生成站点路径 /visitor/ |
scripts/visitor-config.js |
构建时把主题配置写成前端可读文件(必须放在博客根目录的 scripts/) |
改 _config.butterfly.yml
菜单:
1 | menu: |
侧栏配置(api_base 换成你的 Worker 地址):
1 | aside: |
inject(追加,别删原有项;visitor-config.js 必须在 visitor.js 前):
1 | inject: |
本地验证
1 | hexo clean |
http://localhost:4000/侧栏应有「最近访客」http://localhost:4000/visitor/完整列表- 打开任意文章页:侧栏不应再出现这张卡
若失败:F12 → Network 看 /visits;检查 CORS、api_base、D1 绑定。
部署
照常部署博客静态站。Worker 有改动时,仍要回 Cloudflare 粘贴部署。
以后怎么改
| 目的 | 改哪里 |
|---|---|
| 侧栏条数 / 顺序 / 开关 | _config.butterfly.yml → aside.card_visitor |
| 接口逻辑 / 去重 / CORS | 附录 Worker 代码 → Cloudflare 粘贴部署 |
| 看原始数据 | D1 Console:SELECT * FROM visits ORDER BY visited_at DESC LIMIT 20; |
注意
- 可与不蒜子 / Vercount 并存。
- Worker 不要开 Access。
- CORS 必须包含真实访问域名和本地
localhost。
完整代码(可复制)
以下代码供任意读者直接复制到自己的项目使用。请务必替换:
- Worker 里的
ALLOWED_ORIGINS→ 你的博客域名 api_base/ 示例workers.dev地址 → 你的 Worker 地址database_id→ 你在 D1 详情页看到的 UUID
Worker:visitor-api/src/index.js
粘贴到 Cloudflare 编辑器,或保存到本地同名路径(先改 ALLOWED_ORIGINS):
1 | /** |
可选:visitor-api/wrangler.toml
1 | # 第一期用网页部署即可;以后若用 npx wrangler deploy 再填真实 database_id |
Hexo 脚本:scripts/visitor-config.js
放在博客根目录 scripts/ 下(与 package.json 同级):
1 | /** |
前端:source/self/visitor.js
1 | /** |
样式:source/self/visitor.css
1 | /* —— 访客墙(Cloudflare Worker + D1) —— */ |
页面:source/visitor/index.md
1 | --- |




