博客搭到第七篇页面总算是整整齐齐能看了。但每次发完文章心里都会犯嘀咕这东西到底有没有人看哪篇文章比别的更受欢迎静态博客没有后台数据库Hexo 自己给不了这些答案。我把不蒜子统计完整接了一遍从原理到踩坑再到上线整理成了这份详细到每一步的教程。它特别适合跟着本系列在 Win10 环境里搭 Hexo 博客、又不想为统计功能单独维护一套服务的同学只要你已经能在本地跑起 hexo server这篇基本可以照着抄作业。1. 为什么给 Hexo 加统计我最终选了不蒜子1.1 静态博客的统计困境Hexo 生成出来的是一堆纯静态 HTML 文件没有 Node 服务端常驻也没有数据库。我自己以前想过要不写个后端记录访问量但为了一个访问计数去维护服务器、数据库、定时备份成本实在太高而且和个人博客“轻量”的初衷完全背道而驰。在这种前提下可行的统计方案无非几类站点分析工具、评论系统自带的统计、自建后端、以及不蒜子这种专门为静态博客设计的第三方计数脚本。我做了个简单的对比方案是否需要注册能否在页面上直接显示数字部署成本适合场景站点分析工具需要一般不能直接展示中需要埋点想看流量来源、用户画像、停留时长评论系统自带统计部分需要部分能低已经接了评论系统顺便用自建后端统计不需要能高对数据有强定制需求不蒜子统计不用注册核心功能就是显示数字极低一行脚本只想让访问量被看见当时选不蒜子就一个理由它够简单。不用注册、不用申请密钥、不用在后台看报表插一行脚本页脚就能出现“本站总访问量 xx 次”。对于个人博客来说这种“被看见”的仪式感比精确的数据分析重要得多。1.2 不蒜子的一行脚本里藏了什么不蒜子的实现逻辑本质上就是一个跨域计数服务。页面加载时执行它提供的那段 busuanzi.pure.mini.js脚本会完成几件事检查浏览器的 localStorage 里有没有一个用户唯一标识没有就生成一个并存进去。带着当前页面路径和这个用户标识向统计服务器发请求。服务器负责累加计数并把最新数值返回给页面。脚本把返回值填进对应的 span 标签里于是页面上就出现了总访问量、访客数、本页阅读量。理解 localStorage 这一环很重要。它相当于给每个访客发了一张“会员卡”卡存在浏览器本地。下次再来脚本直接刷卡服务器就知道“又是这个人”从而在统计 UV 时去重。这也是为什么清浏览器缓存、开无痕模式、换浏览器都会导致 UV 变多因为“会员卡”没了服务器只能把他当成新访客。1.3 网上教程那么多为什么还经常失败我一开始也照着网上现成的教程复制粘贴结果数字死活不出现。后来排查才发现很多教程的失败点非常集中老教程的脚本地址已经失效。不蒜子后台换过域名早期教程里常见的旧地址早就停用了照抄自然没反应。实际可用的地址我后面会给出。主题不一样。教程默认你用的是某个特定主题但我用的主题模板路径完全不同照着改 footer 文件改完根本不是我那个文件。版本差异。即使同一个主题新版本可能已经在主题配置文件里内置了不蒜子开关旧版本却要手动改模板。两种操作完全是两码事。缺少本地验证步骤。很多人改完直接部署上线然后凭感觉等数字出了错也分不清是网络问题还是代码问题。所以这篇我不会只给一套代码让你复制而是先教会你怎么判断自己的主题属于哪种情况再顺手把 Win10 环境下的操作细节一起讲了。2. 动手前先确认这三件事版本、主题结构和模板位置2.1 Win10 环境下的基础确认不管前面几篇是怎么配置的动手前先花两分钟确认环境。在 Win10 下最常用的方式是 Win R 打开运行窗口输入 cmd 回车进入命令行。先看一下 Hexo 环境是否正常node -v hexo -v能看到版本号就说明基础环境没问题。接下来进入博客目录。如果你的博客放在 D 盘并且路径里带中文或空格建议这样操作d: cd \你的博客目录 dirdir能列出目录内容确认当前路径没进错。这里有个 Win10 特有的坑默认 PowerShell 不支持用把命令串起来执行比如hexo clean hexo g在 PowerShell 里会报错。如果你习惯用 PowerShell可以分开执行或者用分号hexo clean; hexo g; hexo s如果你更习惯 cmd那么是正常支持的。这个细节看起来小但常常卡住新手半小时。2.2 弄清楚你的主题属于哪种“体质”不蒜子的接入方式完全取决于你用的 Hexo 主题。花一分钟看一下博客根目录下的_config.yml里面有个theme:字段写的就是当前主题名。然后打开themes\你的主题名这个目录就能看到主题的真实结构。我通常把主题分成三类类型 A自带不蒜子开关。这类主题比较新主题配置文件里已经有busuanzi、busuanzi_count或visit_counter之类的字段你只需要把enable改成true就行。类型 B没有开关但结构标准。主题有统一的 footer 模板文件所有页面都引用同一个 footer手动加代码进去即可。类型 C结构比较特立独行。首页、文章页、归档页用的模板互相独立footer 不通用这时候就不能只改一个文件得多处添加。快速判断方法很简单用 VS Code 打开整个博客目录在左侧文件树上右键选择“在文件夹中查找”全局搜索busuanzi。如果主题配置或 layout 目录里已经有相关代码说明是 A 类直接去改配置如果搜出来一片空白就要准备手动改了。2.3 备份第一编辑器别用记事本改文件之前先把主题配置文件复制一份到桌面。我就是靠这个习惯救回过一次有一次为了加统计把 footer 模板改乱了整个页面报错直接把备份文件拖回去就恢复了。另外一个 Win10 下特别容易踩的坑是编辑器。系统自带的记事本打开 yml 或模板文件保存时可能会带上 BOM 头或者改变编码导致 Hexo 渲染出来的页面出现乱码或者在配置解析时报错。我强烈建议用 VS Code 这类专业编辑器打开文件后右下角确认编码是 UTF-8再做修改。如果你实在不想装编辑器至少不要用记事本直接改 yml 文件。3. 不蒜子接入实操从改配置到本地看到数字3.1 先走主题自带的开关省心省事如果你的主题是“类型 A”实操会简单到令人感动。找到主题目录下的_config.yml搜索busuanzi或busuanzi_count定位到类似这样的区域busuanzi_count: enable: false site_uv: true site_pv: true page_pv: true把enable改成true保存然后重新生成页面hexo clean hexo g hexo s打开本地预览地址页脚如果出现了统计数字说明主题已经帮你把模板、脚本、样式全部处理好了。不同主题的字段名可能不完全一样有的叫site_uv有的叫site_uv_section但核心思路都是“开开关”。这里要提醒一句如果你用的主题支持“配置覆盖文件”比如_config.主题名.yml优先去那个文件里改别动主题自带的_config.yml。否则以后更新主题版本你改的东西可能被覆盖掉。3.2 手动注入模板的通用方法如果你的主题是 B 类或 C 类就得手动加代码了。先找到 footer 类的模板文件常见的路径和格式有几种themes\你的主题名\layout\_partial\footer.ejsthemes\你的主题名\layout\_partial\footer.swigthemes\你的主题名\layout\_partial\footer.pug文件后缀可能是.ejs、.swig或.pug千万别把.ejs的写法直接粘到.pug文件里Pug 对缩进极其敏感很容易报错。稳妥的做法是打开 footer 文件看看里面已经是什么语法然后在文件末尾追加内容。最通用的不蒜子统计代码块是这样的script async src//busuanzi.icerecord.cn/busuanzi/2.3/busuanzi.pure.mini.js/script span idbusuanzi_container_site_pv styledisplay:none 本站总访问量 span idbusuanzi_value_site_pv/span 次 /span span idbusuanzi_container_site_uv styledisplay:none 访客数 span idbusuanzi_value_site_uv/span 人 /span span idbusuanzi_container_page_pv styledisplay:none 本文阅读量 span idbusuanzi_value_page_pv/span /span这段代码有几个细节值得说明脚本地址用了//开头的协议相对地址。如果你的站点是 https它会自动按 https 加载不会触发浏览器的混合内容拦截。busuanzi_container_*这类外层 span 默认是display:none隐藏状态。不蒜子的脚本加载成功并且拿到数值之后会自动把它改成可见状态。所以不要手贱替它加display:block否则在脚本加载失败时页面上会留下一个空荡荡的“本站总访问量”丑且尴尬。三个核心 span 的 id 含义要记清楚busuanzi_value_site_pv是站点总访问量busuanzi_value_site_uv是站点总访客数busuanzi_value_page_pv是当前页面的阅读量。脚本会自动扫描这些 id 并填数字你不用额外写 JavaScript。保存模板后重新生成并本地预览。注意我每次改完模板都会老老实实执行一次hexo clean再hexo g。Hexo 有缓存不 clean 直接生成有时候会把旧页面残留下来改了半天没效果其实看的是缓存文件。3.3 本地预览时数字不显示怎么办本地地址默认是http://localhost:4000。很多人以为本地预览时统计一定显示不出来其实不蒜子是允许 localhost 请求的正常情况下照样会显示数字。如果本地就没显示先别急着部署。按下 F12 打开开发者工具切到 Console 标签页看有没有红色的报错信息再切到 Network 标签页筛选框输入busuanzi看看脚本请求到底有没有发起、返回状态是什么。如果 Console 里提示脚本文件 404十有八九是地址写得不对回头检查一下是不是抄成了老教程里的失效地址。如果网络请求正常但没有数字那问题多半出在 span 标签的 id 写错了比如少写了一个字母。这些在本地阶段发现比部署上线后再折腾要省事得多。4. 踩坑实录数字不显示、计数不准、文章页没有统计4.1 数字一直是 0 或者页面空白这是最让人抓狂的问题。我在排查这类问题时基本按照固定顺序递进脚本地址失效。不蒜子经历过多轮域名调整网上旧教程大量充斥着已经停用的地址。访问不到脚本后面的 span 自然不会被填充。可以用浏览器直接访问脚本地址能返回一段 JS 就说明地址存活。网络问题。统计服务器有时候响应慢比如在公共 Wi-Fi、校园网这类环境下脚本加载超时。多刷新几次或者换手机流量试试。浏览器插件拦截。广告拦截类插件对第三方统计脚本很敏感可能直接拦截掉。在无痕模式或者关了拦截插件后测试一次能区分是不是插件问题。页面缓存。本地预览或线上页面被浏览器缓存了旧页面没有脚本。按 Ctrl F5 强制刷新去掉缓存重新加载。模板放错位置。比如你把统计代码加进了某个只有首页会引用的局部模板文章页自然看不到。这种情况可以直接看页面源代码搜索busuanzi关键词确认代码到底有没有被渲染出来。还有一个非常隐蔽的坑把统计代码粘进了 Markdown 文章正文里。别人教程里给的是模板代码你复制粘贴到source\_posts\xxx.md里结果页面正文直接显示出一堆 HTML 标签统计却一点反应都没有。记住统计代码要进layout模板不是进文章正文。4.2 PV 和 UV 的概念别混淆看到数字后不少人会疑惑为什么自己刷新了好几次页面站点总访问量涨了但访客数不变这就是 PV 和 UV 的区别。PV 是浏览量每次页面被打开都加 1包括你自己刷新页面。UV 是访客数依赖浏览器本地存储的那个用户标识同一浏览器在一定时间内只算一次。不蒜子的 UV 统计受 localStorage 影响很大清缓存、无痕模式、换浏览器都会导致 UV 增加这是所有前端计数方案的通病不需要追求绝对精确看趋势就足够了。4.3 首页有统计文章页却没有这个问题我在 C 类主题上遇到过。很多主题的首页模板和文章模板是独立的footer 文件可能被多个页面共用也可能各自引用不同的 footer。你只改了首页那个 footer 文件文章页引用的是另一个。排查方法打开一篇文章页面右键查看网页源代码搜索busuanzi如果在源代码里完全找不到那说明文章页的模板里根本没引入这段统计代码。解决办法是把统计代码放到所有页面共同继承的公共布局文件里通常是layout.ejs或layout.swig在 body 底部的某个公共位置加入。如果实在不放心可以在文章模板的post-meta区域单独放一个page_pv的 span脚本全局只引入一次多个 span 都会生效。4.4 HTTPS 页面加载 HTTP 资源被浏览器拦掉如果你给站点配了自定义域名并且开启了 HTTPS就要特别注意脚本地址别写成http://开头的完整地址。浏览器遇到 HTTPS 页面加载 HTTP 资源时会直接拦截控制台会报Mixed Content错误页面上什么都显示不出来。解决办法就是前面代码里写的统一使用//协议相对地址或者直接写成https://的完整地址。顺便说一句如果页面上还有其他第三方资源比如字体、头像之类的也顺手检查一遍这种混合内容问题经常一起出现。4.5 常见问题速查表症状最可能的原因解决建议脚本 404脚本地址是旧版失效地址换成当前可用的地址页面完全没数字浏览器插件拦截了统计脚本关闭拦截插件或无痕模式重试只显示文字没数字span id 写错或脚本未加载检查 id刷新页面首页有、文章页没有模板改错地方改公共布局文件不要只改局部 footer本地有、线上没有线上缓存了旧页面CtrlF5 强刷HTTPS 报 Mixed Content脚本地址写了 http改用//协议相对地址4.6 一个兜底方案把脚本放到本地第三方统计服务再稳也有可能因为域名解析、服务器波动而抽风。如果你实在不放心可以把busuanzi.pure.mini.js这个文件下载下来放到博客主题的source\js目录里然后把模板里的脚本地址改成script async src/js/busuanzi.pure.mini.js/script这样页面加载的脚本文件来自你自己的服务器/静态空间不会再出现“脚本文件本身加载不出来”的情况。但有一点必须说清楚脚本本地化只是保证了 JS 文件能加载真正的计数接口还是在不蒜子的远程服务器上。如果统计服务器本身挂了本地化脚本同样拿不到数据。这个方案是兜底不是包治百病。5. 上线部署后的验证与几个提升体验的做法5.1 部署流程与上线检查清单本地预览确认没问题后就可以部署上线了。先退出本地预览Ctrl C然后hexo clean hexo g hexo d部署完成后打开线上站点按 Ctrl F5 强制刷新一次等一两秒看页脚统计数字。我习惯按下面这个清单逐项检查首页能看到站点总访问量数字不为 0。访客数也正常显示并且数值小于等于访问量正常情况下 UV 不会超过 PV。随机打开一篇文章页面上能看到“本文阅读量”并且这个数字和首页的站点总访问量是分开统计的。手机上关掉 Wi-Fi 用流量访问一次确认不同网络环境下页面也正常。浏览器地址栏的小锁图标正常没有红色警告。另外提醒一下不蒜子按域名区分站点不同域名、不同端口看到的统计数字是独立的。如果你本地 localhost 显示了一部分数字部署到线上域名又是一个全新的计数这不是出 bug是正常现象。5.2 控制统计展示的细节不是所有人都想在页面上展示全部三类统计。有些人只想显示总访问量不想暴露访客数有些人不希望“本文阅读量”出现在文章顶部怕自己刚发文章就被人看到个位数。控制方式很简单不需要动脚本只需要决定保留哪些 span。不想显示的统计直接把对应的 span 从模板里删掉就行其他统计照常工作。比如不想要访客数就删掉busuanzi_container_site_uv那一整段站点总访问量和文章阅读量仍然会正常显示。如果想让某些特定页面完全不显示统计可以通过 Hexo 的页面变量做判断。以 ejs 模板为例在统计代码外层套一个条件% if (!(page.layout post page.no_busuanzi true)) { % span idbusuanzi_container_site_pv styledisplay:none.../span % } %然后在文章的 Front Matter 里加一个no_busuanzi: true那篇文章就不会显示统计了。这个方法对于“关于我”“隐私声明”这类不太需要展示访问量的页面很实用。5.3 统计、字数与评论信息的整合博客搭到这一步页脚光秃秃一串数字其实不太好看。很多主题提供文章信息栏post-meta可以把“本文阅读量”和字数统计、评论区信息整合到同一行。比如在文章模板的 meta 区域放入span idbusuanzi_container_page_pv styledisplay:none 本文阅读量 span idbusuanzi_value_page_pv/span /span脚本依然只需要在全局引入一次页面上任意位置的 span 都会被自动填充不需要每个 span 都配一个 script 标签。把统计放在文章标题下方比放在页脚更容易被访客看到对内容创作者的正反馈也更强。5.4 别把统计当成唯一的数据来源不蒜子解决的是“页面显示数字”这个需求但它给不了用户的来源渠道、停留时长、跳出率这些流量分析数据。如果你把博客当成一个长期经营的项目想认真分析读者从哪里来、喜欢看什么可以考虑在不蒜子之外再引入一个站点分析工具把埋点统计代码加到页面的 head 区域。两者不冲突一个负责“给你看”一个负责“给你分析”。我的建议是不要一开始就全副武装。先把不蒜子跑通享受一下访问量从 0 到 1 的快乐等博客内容稳定更新了再考虑要不要上更重的分析工具。6. 写在最后一点实操体会不蒜子统计接入本身不复杂但它在整个 Hexo 博客系列里承担着一个微妙的角色让“维护个人主页”这件事从单向输出变成了双向反馈。以前发完文章阅读量全靠自己脑补现在数字摆在页脚每次打开网站都有种“被看到了”的实感。我个人实操下来最大的体会是这类第三方功能接入最难的不是代码而是判断“该改哪里”。同一个教程别人一条直线走通你可能因为主题结构不同、脚本地址过期、PowerShell 不支持这些弯弯绕绕硬生生卡一下午。所以这篇特意把“先看主题配置再定位模板最后本地验证”的流程放在前面就是希望你能少走这些弯路。最后再分享一个小技巧每次改完主题文件hexo clean一定要记得执行这几乎成了我发布前的肌肉记忆。清缓存、生成、本地预览、部署这一套流程走顺之后后面再加赞赏、地图、SEO 这些功能时节奏都会快很多。博客真正开始有自己的样子往往就是从这些一个个小功能落地开始的。