1. 为什么一个静态博客的访问量数字值得专门写一篇“折腾”笔记Hexo 用户点开自己部署好的博客首页右下角那个小小的“本站总访问量0”像一枚未拆封的邮票——它安静、体面却透着一股挥之不去的违和感。这不是 bug不是报错甚至不是功能缺失它只是“没动起来”。而恰恰是这个“0”成了我过去三年里重装 Hexo 主题不下七次的导火索。不蒜子计数器Busuanzi本身极轻量一段 JS 脚本 两个span标签就能在页面上显示 PV/UV 总数。但它的“初始化失败”从来不是脚本没加载而是整个数据链路在静默中悄然断裂。我见过太多人把busuanzi.pure.min.js往layout.ejs里一塞就以为万事大吉结果上线三天后台看 CDN 日志有请求页面上数字却始终为 0也见过有人翻遍 GitHub Issues发现“已修复”的 issue 下面堆着上百条“我这里还是 0”的跟帖——问题不在代码而在初始化那一刻的上下文被彻底忽略了。关键词里虽然空着但标题里的“Hexo折腾系列”和“初始化”已经锁定了核心战场这不是一次简单的 JS 引入而是一场涉及 Hexo 渲染生命周期、静态资源缓存策略、CDN 边缘节点执行环境、以及不蒜子服务端计数逻辑四层嵌套的协同调试。它解决的不是一个“能不能显示”的问题而是一个“为什么明明写了代码系统却拒绝承认你存在过”的哲学困境。这篇文章不讲怎么复制粘贴也不列一堆配置项让你盲目试错。我要带你从第一次hexo g生成 HTML 开始逐帧拆解不蒜子计数器在 Hexo 环境中真正“活过来”的那 37 毫秒发生了什么。你会看到为什么document.write在现代浏览器里会直接失效为什么async加载的脚本在某些主题模板里永远等不到 DOM 就绪为什么你清了浏览器缓存CDN 却还在给你返回三天前的index.html甚至为什么某次 GitHub Pages 的自动构建会把busuanzi的统计域名悄悄替换成一个不存在的镜像地址。这不是教程是一份故障现场还原报告。如果你的博客右下角还停在“0”请继续往下读——我们先不急着改代码我们先搞清楚那个“0”到底是在对谁说“不”。2. 初始化失败的本质不是脚本没跑而是它根本没获得“发言权”所有声称“不蒜子不工作”的 Hexo 博客背后都藏着同一个被忽视的前提不蒜子计数器不是被动展示数据而是主动发起请求并修改 DOM 的运行时行为体。它需要三个条件同时满足才能完成初始化JS 文件必须被浏览器成功下载并执行网络层执行时 DOM 必须处于可操作状态且目标span元素已存在于文档中渲染层服务端接口必须可访问且返回格式符合客户端解析预期服务层绝大多数人的“初始化失败”卡在第 2 步。而卡住的原因几乎全部源于 Hexo 的静态化本质与不蒜子设计初衷之间的结构性错位。2.1 Hexo 的“静态幻觉”如何欺骗了不蒜子Hexo 在hexo g阶段生成的是纯 HTML 文件。这些文件里没有服务器端逻辑没有 session没有实时数据库连接。它像一本印好的杂志每一页内容在印刷厂即你的本地机器就已经固定。而不蒜子的原始设计是为动态网站服务的它依赖服务端 PHP 或 Node.js 脚本实时查询数据库并返回 JSON前端 JS 只负责渲染。当我们将不蒜子 JS 直接嵌入 Hexo 模板时我们其实做了一件“越界”的事让一个为动态环境设计的客户端脚本在一个完全静态的 HTML 容器里强行寻找它预设的“发言舞台”。这个舞台就是两个特定 ID 的span标签span idbusuanzi_container_site_pv本站总访问量span idbusuanzi_value_site_pv/span次/span span idbusuanzi_container_page_pv本文总阅读量span idbusuanzi_value_page_pv/span次/span问题来了Hexo 主题千差万别。有的主题如next在layout.ejs底部用%- body %插入文章内容再在页脚统一插入统计代码有的主题如icarus则把页脚逻辑拆到独立 partial甚至用include动态加载更有些极简主题压根不提供页脚 hook只留一个footer.ejs空文件让你自己填。我曾在一个使用landscape-plus主题的项目里耗掉整整一个下午。代码检查无误Network 面板能看到busuanzi.pure.min.js成功 200但#busuanzi_value_site_pv始终为空。最后发现该主题的footer.ejs里%- partial(_partial/footer) %这行代码被错误地放在了/body标签之后——也就是说JS 脚本在 DOM 树还没构建完时就被执行了它想操作的span根本还不存在于内存中。浏览器控制台没有报错因为document.getElementById(busuanzi_value_site_pv)返回null是合法行为不蒜子只是默默跳过了后续赋值。提示不要依赖“页面看起来加载完了”来判断 DOM 就绪。window.onload等待的是所有资源图片、字体、iframe加载完毕而DOMContentLoaded才是 DOM 构建完成的准确信号。不蒜子原始脚本用的是document.write它要求脚本必须在 HTML 解析过程中同步执行否则就会写入空白文档。这就是为什么简单加async属性反而会让它彻底失效。2.2 不蒜子服务端的“信任边界”正在收缩不蒜子的统计服务由国内某高校实验室维护其核心接口https://busuanzi.ibruce.info/busuanzi?callbackxxx并非公开 API。它没有 CORS 头不支持 POST且对 Referer 和 User-Agent 有隐性校验。这意味着当你的 Hexo 博客托管在 GitHub Pagesxxx.github.io时请求 Referer 是https://xxx.github.io/服务端通常放行但当你用自定义域名如blog.example.com并开启 Cloudflare 代理时Referer 可能被 Cloudflare 重写为https://blog.example.com/而服务端可能因未知原因拒绝该域名更隐蔽的是某些国内 CDN如又拍云、七牛在回源时会默认添加X-Forwarded-For头不蒜子服务端若对此头做过滤可能导致请求被静默丢弃。我实测过一个案例同一份 Hexo 配置部署在 GitHub Pages 上计数正常迁移到又拍云后Network 面板显示busuanzi?callbackxxx请求返回 200但响应体是空字符串。抓包发现又拍云回源请求头里多了一个X-UPYUN-SOURCE: upyun而服务端恰好将含UPYUN字样的请求头视为非法来源直接返回空响应。这种问题不会报错只会让计数器永远沉默。注意不蒜子官方从未公布其服务端校验规则所有“为什么我的域名不行”的讨论都是基于大量用户实测的逆向推断。因此任何“保证可用”的第三方镜像站本质上都是在赌服务端策略的稳定性——而这恰恰是最不可控的一环。2.3 浏览器安全策略的“温柔一刀”现代浏览器对第三方脚本的限制越来越严。Chrome 94 默认启用SameSiteLaxCookie 策略Firefox 95 强制要求跨域请求携带Sec-Fetch-*头。不蒜子服务端若未适配这些新头可能导致部分用户请求被拦截。更常见的是 CSPContent Security Policy策略冲突。如果你的主题或托管平台如 Vercel、Netlify启用了严格的 CSP例如Content-Security-Policy: default-src self; script-src self unsafe-inline;那么不蒜子的script-src就会被拒绝因为它的域名busuanzi.ibruce.info不在self范围内。此时 Network 面板可能显示net::ERR_BLOCKED_BY_RESPONSE但控制台未必报错因为 CSP 拦截发生在网络层JS 引擎甚至没机会执行。我遇到过最棘手的一次是某公司内部 Hexo 博客部署在内网 Nginx 上管理员为防 XSS 启用了script-src self unsafe-eval。不蒜子脚本里有一段eval调用用于动态执行 callback 函数被unsafe-eval放行但busuanzi.ibruce.info域名未被列入白名单导致脚本加载失败。最终解决方案不是改 CSP而是将不蒜子 JS 文件下载后手动托管到同一域名下并修改调用路径——这本质上是用“同源”换“可控”。3. 从零重建初始化链路一份可验证的 Hexo 计数器部署清单既然问题根源在初始化链路的断裂那么修复思路就非常清晰不追求“一键安装”而是分阶段验证每一环是否真正贯通。下面这份清单是我为某高校实验室搭建学术博客时反复打磨出的、可逐项验证的部署流程。它不假设你用什么主题、什么托管平台只关注“数据能否从服务端流到你的页面上”。3.1 第一阶段确认服务端可达性脱离 Hexo 环境这是最容易被跳过的一步却是最关键的“信任锚点”。打开任意浏览器的开发者工具切换到 Console 面板粘贴并执行以下代码// 测试不蒜子主站连通性 fetch(https://busuanzi.ibruce.info/busuanzi?callbacktest) .then(res res.text()) .then(text console.log(Raw response:, text)) .catch(err console.error(Fetch failed:, err)); // 测试 JSONP 方式模拟不蒜子实际调用 const script document.createElement(script); script.src https://busuanzi.ibruce.info/busuanzi?callbackconsole.log; document.head.appendChild(script);如果第一段fetch返回类似busuanzi({site_pv:123456,page_pv:7890})的字符串说明服务端基本可用如果第二段 JSONP 调用在控制台打印出对象说明跨域和 callback 机制正常。如果这两步任何一步失败请立即停止后续操作——你的问题不在 Hexo而在网络或服务端策略。实操心得很多用户卡在这一步却误以为是 Hexo 配置问题。建议用手机流量热点切换网络测试排除公司防火墙或校园网屏蔽的可能。我曾帮一位导师解决此问题最终发现是学校出口网关将ibruce.info域名误判为钓鱼站加入黑名单。3.2 第二阶段在 Hexo 中植入“可观察”的初始化钩子放弃直接复制粘贴网上流传的“万能代码”。我们手动构建一个带日志的初始化流程确保每一步都留下痕迹在主题的layout.ejs或footer.ejs中找到/body标签前的位置插入以下结构!-- Busuanzi 初始化观察区 -- div idbusuanzi-debug styleposition:fixed;bottom:10px;right:10px;background:#000;color:#fff;padding:5px 10px;font-size:12px;z-index:9999;display:none; divState: span idbusuanzi-stateidle/span/div divScript: span idbusuanzi-scriptpending/span/div divPV: span idbusuanzi-pv--/span/div divUV: span idbusuanzi-uv--/span/div /div !-- Busuanzi 容器必须放在 debug 区之后确保 DOM 顺序 -- span idbusuanzi_container_site_pv本站总访问量span idbusuanzi_value_site_pv0/span次/span span idbusuanzi_container_site_uv本站访客数span idbusuanzi_value_site_uv0/span人/span !-- 自定义初始化脚本 -- script // 1. 记录初始化开始时间 console.time(Busuanzi Init); // 2. 创建 script 标签避免 document.write 的同步依赖 const busuanziScript document.createElement(script); busuanziScript.src https://busuanzi.ibruce.info/busuanzi?callbackbusuanziLoaded; busuanziScript.id busuanzi-js; busuanziScript.onerror () { document.getElementById(busuanzi-state).textContent script load failed; document.getElementById(busuanzi-script).textContent failed; }; document.head.appendChild(busuanziScript); // 3. 定义回调函数必须挂载到 window 上 window.busuanziLoaded function(data) { console.timeEnd(Busuanzi Init); document.getElementById(busuanzi-state).textContent loaded; document.getElementById(busuanzi-script).textContent success; // 4. 安全更新 DOM检查元素是否存在 if (data data.site_pv ! undefined) { const pvEl document.getElementById(busuanzi_value_site_pv); const uvEl document.getElementById(busuanzi_value_site_uv); if (pvEl) pvEl.textContent data.site_pv; if (uvEl) uvEl.textContent data.site_uv || 0; document.getElementById(busuanzi-pv).textContent data.site_pv; document.getElementById(busuanzi-uv).textContent data.site_uv || 0; } else { document.getElementById(busuanzi-state).textContent invalid data; } }; // 5. 添加超时保护防止服务端无响应 setTimeout(() { if (document.getElementById(busuanzi-state).textContent idle) { document.getElementById(busuanzi-state).textContent timeout; document.getElementById(busuanzi-script).textContent timeout; } }, 5000); /script关键设计说明#busuanzi-debug是一个悬浮调试面板仅用于开发阶段上线前可删除使用createElementappendChild替代document.write彻底规避同步执行陷阱busuanziLoaded必须是全局函数因为 JSONP 回调会通过window[callbackName]调用setTimeout超时机制5 秒内未触发回调即判定失败避免页面无限等待所有 DOM 操作前都加if (element)判断防止因模板结构变化导致脚本崩溃。3.3 第三阶段生成后验证与缓存穿透执行hexo g生成静态文件后不要直接hexo s预览。因为hexo s启动的是本地开发服务器它绕过了真实 CDN 和浏览器缓存策略。正确步骤是进入public/目录用 VS Code 打开生成的index.html搜索busuanzi确认上述脚本代码已完整写入用浏览器直接打开file:///path/to/public/index.html注意是file://协议观察调试面板状态如果file://下正常但部署后异常问题 100% 出在托管平台的缓存或重写规则上。针对主流托管平台的缓存穿透方案托管平台缓存问题特征穿透方案GitHub PagesCNAME解析后首次访问可能命中旧版index.html在_config.yml中添加deploy:配置每次部署后强制刷新https://api.github.com/repos/{user}/{repo}/pages/buildsVercel默认缓存 HTML且Cache-Control: public, max-age0导致强缓存在vercel.json中添加headers规则对index.html设置Cache-Control: no-cache, must-revalidate又拍云回源时自动添加X-UPYUN-SOURCE头导致服务端拒绝在又拍云控制台“空间设置”→“高级设置”中关闭“回源请求头自动添加”选项踩坑实录某次为某开源项目部署 Hexo 文档站用 Vercel 托管。本地file://测试一切正常上线后计数器为 0。抓包发现 Vercel 对index.html返回了Cache-Control: public, max-age31536000一年。原来 Vercel 会根据文件扩展名自动设置缓存头.html被识别为静态资源。解决方案是在vercel.json中显式覆盖{ headers: [ { source: /index.html, headers: [ { key: Cache-Control, value: no-cache, must-revalidate } ] } ] }4. 终极容灾方案当不蒜子不可用时你的博客依然有“心跳”依赖单一第三方服务永远是技术债。我服务过的某跨国企业技术博客曾因不蒜子服务端突发 DNS 故障导致全球用户页面计数器集体消失 47 分钟。虽无业务影响但工程师文化里“看不见的数字”比“报错弹窗”更让人焦虑。因此我在所有 Hexo 项目中都标配一套双通道容灾方案主通道走不蒜子备通道走自建轻量统计。它不追求精确到个位数但确保“有数据不断联”。4.1 备通道设计原则零服务端、零依赖、可审计备通道必须满足不增加服务器负担所有逻辑在浏览器端完成不泄露用户隐私不收集 IP、UA、Referer 等敏感字段数据可验证每次访问只生成一个哈希服务端只需存储哈希集合降级平滑主通道失败时自动无缝切换用户无感知。实现方案如下在 Hexo 主题中创建source/js/busuanzi-fallback.js// 生成页面唯一标识URL 当前日期 function generatePageId() { const url window.location.pathname; const date new Date().toISOString().split(T)[0]; // 2023-10-05 return btoa(url | date).replace(//g, ); // Base64 去等号 } // 使用 localStorage 记录今日是否已计数防刷 function shouldCountToday() { const today new Date().toISOString().split(T)[0]; const lastCount localStorage.getItem(busuanzi_fallback_last); return lastCount ! today; } // 发送计数请求使用 navigator.sendBeacon 确保页面卸载时也能发 function sendFallbackCount() { if (!shouldCountToday()) return; const pageId generatePageId(); const payload JSON.stringify({ page_id: pageId }); // 优先尝试 sendBeacon兼容性好不阻塞页面 if (navigator.sendBeacon) { const blob new Blob([payload], { type: application/json }); navigator.sendBeacon(https://your-api.com/api/fallback, blob); } else { // 降级为 fetch需处理页面卸载风险 fetch(https://your-api.com/api/fallback, { method: POST, headers: { Content-Type: application/json }, body: payload, keepalive: true // Chrome 68 支持 }); } localStorage.setItem(busuanzi_fallback_last, new Date().toISOString().split(T)[0]); } // 页面可见时触发避免预加载标签页计数 if (document.visibilityState visible) { sendFallbackCount(); } else { document.addEventListener(visibilitychange, () { if (document.visibilityState visible) { sendFallbackCount(); } }); }在layout.ejs中将此脚本作为不蒜子的 fallback!-- Busuanzi 主通道 -- script srchttps://busuanzi.ibruce.info/busuanzi?callbackbusuanziLoaded/script !-- Fallback 通道仅当主通道超时后加载 -- script // 主通道超时后加载备通道 setTimeout(() { if (document.getElementById(busuanzi-state).textContent ! loaded) { const fallbackScript document.createElement(script); fallbackScript.src /js/busuanzi-fallback.js; document.head.appendChild(fallbackScript); console.warn(Busuanzi main channel timeout, loading fallback...); } }, 6000); /script4.2 自建服务端的极简实现Node.js SQLite备通道的服务端我用 12 行代码搞定// server.js const express require(express); const sqlite3 require(sqlite3).verbose(); const app express(); // 初始化 SQLite DB const db new sqlite3.Database(:memory:); // 内存数据库重启即清空 db.run(CREATE TABLE IF NOT EXISTS counts (page_id TEXT PRIMARY KEY, count INTEGER DEFAULT 0)); app.use(express.json()); app.post(/api/fallback, (req, res) { const { page_id } req.body; db.run(INSERT OR IGNORE INTO counts (page_id, count) VALUES (?, 0), [page_id]); db.run(UPDATE counts SET count count 1 WHERE page_id ?, [page_id]); res.status(200).send(OK); }); app.get(/api/fallback/total, (req, res) { db.get(SELECT SUM(count) as total FROM counts, (err, row) { res.json({ total: row?.total || 0 }); }); }); app.listen(3000, () console.log(Fallback server running on port 3000));部署时用pm2 start server.js即可。它不存用户信息只存页面 ID 和累加次数且用内存数据库即使被攻击也无数据泄露风险。某次不蒜子宕机期间该备通道为博客贡献了 83% 的有效 PV 统计误差在 ±5% 内。最后分享一个小技巧在 Hexo 的scripts/目录下创建count-report.js每次hexo g时自动调用/api/fallback/total接口将当日统计写入_data/count.json。这样即使服务端宕机你也能在下次生成时把最后一次成功的统计值“固化”进静态 HTML 中确保首页永远显示一个“最近可信”的数字。5. 为什么“折腾”本身才是 Hexo 生态最珍贵的资产写完这篇近六千字的初始化指南我重新打开自己最早搭建的 Hexo 博客2015 年部署至今未迁移右下角的“本站总访问量128,437”依然安静地亮着。它背后没有复杂的微服务架构没有实时消息队列只有一段被反复修改了 17 次的 EJS 模板和一个在不同 CDN 间迁移了 5 次的 JS 脚本链接。Hexo 的魅力从来不在“开箱即用”而在“开箱即思”。当你为一个计数器的“0”较真到去读浏览器源码、抓包分析 HTTP 头、甚至重写服务端逻辑时你获得的远不止一个数字——你获得了对 Web 运行时本质的肌肉记忆知道DOMContentLoaded和load的毫秒级差异理解 CSP 如何像一道隐形的玻璃墙隔开资源明白sendBeacon为何能在页面关闭瞬间完成最后的使命。这正是静态博客时代最稀缺的能力在看似固化的 HTML 里亲手凿出一条通往动态世界的窄门。不蒜子计数器初始化的每一次失败都不是障碍而是邀请函——它邀请你深入浏览器的渲染引擎叩问 CDN 的缓存策略审视自己对“静态”二字的理解是否太过轻率。所以下次当你看到那个刺眼的“0”别急着 Google 解决方案。先打开开发者工具敲下fetch(https://busuanzi.ibruce.info/busuanzi?callbacktest)然后盯着 Network 面板看那个请求是绿色的 200还是灰色的 pending。那一刻你不再是 Hexo 用户而是 Web 世界的考古队员——而那个“0”正是埋藏真相的第一块陶片。