在折腾完博客的 UI 和排版后，是时候关注一下「里子」了。

对于个人博客来说，Google Analytics ( GA4 ) 显得过于庞大且复杂。我们更关心的是：用户到底看了什么？他们在哪里停留？为什么他们离开了？

这时，Microsoft Clarity 是一个绝佳的选择。它完全免费、不限流量，且提供两个杀手级功能：热力图 ( Heatmaps ) 和 会话录屏 ( Session Recordings )。

本文记录了如何在 Hugo PaperMod 主题中，以最符合工程规范的方式接入 Clarity。

1. 为什么选择 Clarity？

  • 可视化强：GA4 给你一堆数字，Clarity 给你一张热力图。你可以直观地看到用户在文章的哪个段落停留最久，或者点击了哪个无效链接。
  • 上帝视角：录屏功能可以回放用户的浏览轨迹 ( 已脱敏 ) ，这对于优化排版和发现 Bug 极其有用。
  • 轻量：脚本异步加载，对加载速度影响极小。

2. 获取 Project ID

  1. 登录 Microsoft Clarity 并创建项目。
  2. 进入 Settings -> Overview。
  3. 复制 Project ID ( 通常是一串 10 位的字符，如 j8x7s2k... ) 。

注意：官方会提供一段包含 <script> 的完整代码，不要复制整段。作为追求代码整洁的工科男，我们要用 Hugo 的方式来封装它。

3. 工程化接入方案

PaperMod 预留了 extend_head.html 接口，这是引入第三方脚本的最佳位置。

我采用了 「配置与逻辑分离」 的方案：在 HTML 中写通用模板，在 hugo.toml 中填具体 ID。这样以后换 ID 或关闭统计，只需改配置，不用动代码。

第一步：创建模板文件

在博客根目录下创建文件：layouts/partials/extend_head.html。

  • ( 注：如果文件已存在，直接追加内容 ) *

写入以下代码：

{{- if .Site.Params.clarity_id }}
<!-- Microsoft Clarity Code -->
<script type="text/javascript">
 ( function ( c,l,a,r,i,t,y ) {
        c [a]=c [a]||function ( ) {( c [a].q=c [a].q||[] ) .push ( arguments )};
        t=l.createElement ( r ) ;t.async=1;t.src="https://www.clarity.ms/tag/"+i;
        y=l.getElementsByTagName ( r ) [0];y.parentNode.insertBefore ( t,y ) ;
 }) ( window, document, "clarity", "script", "{{ .Site.Params.clarity_id }}" ) ;
</script>
{{- end }}

代码解析：

  • {{- if .Site.Params.clarity_id }}：这是一个开关。只有当你在配置文件里填了 ID，这段 JS 才会加载。没填就是纯净版，方便本地调试。
  • t.async=1：确保脚本是异步加载的，不会阻塞页面渲染。

第二步：修改配置文件

打开博客根目录下的 hugo.toml( 或 config.yml ) ，找到 [params] 区域，添加你的 ID：

[params]
    # ... 其他配置 ...

    # Microsoft Clarity
    clarity_id = "你的_Clarity_Project_ID"

4. 验证与性能

提交代码并部署到 Cloudflare Pages 后，打开博客，按下 F12 进入开发者工具：

  1. Network 面板：搜索 clarity，应该能看到相关的数据包请求 ( status 200 ) 。
  2. 性能影响：得益于 async 异步加载和 Cloudflare 的全站加速，Clarity 对 **LCP ( 最大内容渲染时间 ) ** 的影响几乎可以忽略不计。博客依然是秒开。

5. 总结

相比于直接把 <script> 标签硬编码到网页里，这种参数化的配置方式显然更加优雅和健壮。

大概等待 30 分钟到 2 小时，Clarity 后台就会出现数据。接下来，就是享受「上帝视角」，观察访客如何在你的数字领地上行走的乐趣了。

💡 方案 B：直接粘贴官方代码 ( 简单粗暴 )

如果不喜欢逻辑和配置分离，直接简单粗暴，直接把 <script> 标签塞进 layouts/partials/extend_head.html 里。