总结摘要
本文详细介绍如何为Hugo Next主题添加开源统计工具Umami的支持。通过自定义analytics文件和修改主题配置，实现对开源统计工具Umami的完整集成。文章涵盖了实现原理、具体步骤、配置方法和验证过程，为使用Hugo博客的用户提供了完整的Umami集成解决方案。
概述
最近我将博客的统计工具从其他方案迁移到了开源的
Umami
，但发现 Hugo 的 Next 主题默认并不支持 Umami。经过一番研究，我成功地为该主题添加了 Umami 统计支持。本文将详细介绍实现过程，为使用 Hugo 博客的用户提供一个完整的 Umami 集成解决方案。
主题官网：
Github-hugo-next
先声明一下，这个主题默认支持51La、百度、谷歌、Cloudflare、不蒜子、谷歌统计，但是不支持Umami。而且已经做到比较成熟
为什么选择 Umami？
Umami
是一个开源的、注重隐私的网站统计解决方案，它具有以下优点：
- 轻量级：脚本大小仅约 1 KB，不会影响网站加载速度
- 注重隐私：不会收集个人身份信息，符合 GDPR 和 ePrivacy 规定
- 简洁直观的界面：提供清晰的数据展示和易于理解的图表
- 支持自托管：完全掌控自己的数据，无需依赖第三方服务
- 完全开源：代码完全透明，可自行修改和部署
- 数据可视化：提供丰富的数据统计和可视化图表
与 Google Analytics 等传统统计工具相比，Umami 更加注重用户隐私，同时提供了简洁易用的界面和功能。
实现原理
Hugo 主题的统计功能通常通过在页面的 <head> 部分注入统计脚本来实现。Umami 统计需要在每个页面中包含一个 JavaScript 文件，该文件会收集页面访问数据并发送到你的 Umami 实例。
实现方法是通过创建自定义的 analytics 模板文件，并修改主题的 analytics 加载逻辑，使其支持 Umami 统计配置。
具体实现步骤
准备工作
首先，确保你已经拥有一个可访问的 Umami 实例。如果你还没有，可以按照官方文档进行部署：
1
2
3
4
5
6
7
8
| # 使用 Docker 部署 Umami
docker run -d --restart=always --name umami \
-p 3000:3000 \
-e DATABASE_URL="postgresql://[数据库用户名]:[数据库密码]@[数据库主机]:[数据库端口]/[数据库名]" \
-e APP_SECRET="任意长随机字符串" \
-e HASH_LENGTH="8" \
-e DISABLE_TELEMETRY="true" \
ghcr.io/umami-software/umami:postgresql-latest
|
部署完成后，创建一个网站并获取网站 ID 和追踪脚本 URL。
创建自定义 Analytics 文件
首先，我们需要创建一个自定义文件来处理 Umami 统计代码：
1
| mkdir -p layouts/partials/_thirdparty/analytics
|
然后创建 layouts/partials/_thirdparty/analytics/umami.html 文件
粘贴以下内容：
1
2
3
4
5
| {{- if .Site.Params.analytics.umami.enable -}}
<!-- Umami Analytics -->
<script async defer data-website-id="{{ .Site.Params.analytics.umami.websiteId }}" src="{{ .Site.Params.analytics.umami.scriptUrl }}"></script>
<!-- End Umami Analytics -->
{{- end -}}
|
这个文件使用了 Hugo 的模板语法，只有在 enable 参数设置为 true 时才会输出统计脚本。
修改主题文件
接下来，我们需要修改主题的 analytics.html 文件，以支持 Umami 统计。该文件位于：
1
| themes/hugo-theme-next/layouts/_partials/head/script/analytics.html
|
将以下代码添加到该文件的末尾（在其他统计配置之后）：
1
2
3
| {{ if isset .Site.Params.analytics "umami" }}
{{ partial "_thirdparty/analytics/umami.html" . }}
{{ end }}
|
这段代码检查配置中是否包含 umami 设置，如果有则加载我们创建的自定义 Umami 模板。
配置 Umami 统计
在 hugo.yaml 配置文件中添加 Umami 统计的配置：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
| params:
analytics:
# 51La 站点统计
# 更多信息请参考：https://invite.51.la/1NUfGTS1?target=V6
# 51La Analytics
# See: https://invite.51.la/1NUfGTS1?target=V6
#laId: #<anaytics_id>
# 百度统计
# Baidu Analytics
#baidu: #<anaytics_id>
# 谷歌统计
# Google Analytics
#google: #<anaytics_id>
# 谷歌统计
# Cloudflare Analytics
#cloudflare: #<cloudflare_id>
# 不蒜子统计
# Show Views / Visitors of the website / page with busuanzi.
# For more information: http://ibruce.info/2015/04/04/busuanzi/
busuanzi:
visitorsIcon: fa fa-user
viewsIcon: fa fa-eye
# Umami 统计
# Umami Analytics
umami:
# 启用Umami统计
enable: true
# 你的Umami网站ID
websiteId: "your-umami-website-id"
# Umami脚本的URL，例如：https://umami.example.com/script.js
scriptUrl: "https://your-umami-instance.com/script.js"
|
请确保将以下参数替换为你的实际值：
your-umami-website-id：在 Umami 实例中创建网站时获得的 IDhttps://your-umami-instance.com/script.js：你的 Umami 实例的追踪脚本 URL
验证集成
完成上述步骤后，重新构建并启动你的 Hugo 网站：
要验证集成是否成功，可以执行以下操作：
- 打开浏览器，访问你的网站
- 右键点击页面，选择"查看页面源代码"
- 搜索页面源代码中是否包含 Umami 的脚本标签
- 在开发者工具的"网络"标签中，查看是否有对 Umami 脚本的请求
如果一切正常，你应该能看到类似这样的代码：
1
| <script async defer data-website-id="your-umami-website-id" src="https://your-umami-instance.com/script.js"></script>
|
同时，访问你的 Umami 控制面板，应该能看到实时访问数据。
故障排除
如果 Umami 统计没有正常工作，请检查以下几点：
检查配置参数
- 确认
umami.html 文件已正确创建 - 确认
analytics.html 文件已正确修改 - 确认配置文件中的
websiteId 和 scriptUrl 已正确设置 - 确认
enable 参数设置为 true
检查 Umami 实例
- 确认 Umami 实例可正常访问
- 确认网站 ID 与 Umami 实例中的 ID 一致
- 检查浏览器控制台是否有 JavaScript 错误
检查网络请求
- 使用浏览器开发者工具的"网络"标签
- 查看是否有对 Umami 脚本的请求
- 检查请求状态是否为 200
扩展功能
自定义 Umami 配置
你还可以为 Umami 添加更多自定义配置，例如：
1
2
3
4
5
6
7
8
9
10
11
| {{- if .Site.Params.analytics.umami.enable -}}
<!-- Umami Analytics with Custom Configuration -->
<script>
var _umami = _umami || [];
_umami.push(['track', {
websiteId: '{{ .Site.Params.analytics.umami.websiteId }}',
hostUrl: '{{ .Site.Params.analytics.umami.hostUrl }}'
}]);
</script>
<script async defer src="{{ .Site.Params.analytics.umami.scriptUrl }}"></script>
{{- end -}}
|
同时使用多个统计工具
你可以在配置中同时启用多个统计工具，包括 Umami 和其他统计工具。它们之间通常不会冲突。
更新主题时的注意事项
这是一个关键部分，需要特别注意：当你更新 Hugo Next 主题时，直接修改的主题文件将会被覆盖，导致 Umami 集成失效。以下是处理主题更新的几种方法：
方法一：备份和恢复修改
备份修改：在更新主题之前，备份你修改过的文件：
1
| cp themes/hugo-theme-next/layouts/_partials/head/script/analytics.html themes/hugo-theme-next/layouts/_partials/head/script/analytics.html.bak
|
更新主题：执行主题更新（例如通过 Git 或手动替换）
重新应用修改：更新完成后，将你的修改重新应用到新的 analytics.html 文件中：
1
2
3
4
| # 在新文件末尾添加 Umami 支持代码
echo '{{ if isset .Site.Params.analytics "umami" }}' >> themes/hugo-theme-next/layouts/_partials/head/script/analytics.html
echo ' {{ partial "_thirdparty/analytics/umami.html" . }} ' >> themes/hugo-theme-next/layouts/_partials/head/script/analytics.html
echo '{{ end }}' >> themes/hugo-theme-next/layouts/_partials/head/script/analytics.html
|
方法二：使用 Git 补丁
创建补丁：
1
2
| # 创建包含修改的补丁文件
git diff themes/hugo-theme-next/layouts/_partials/head/script/analytics.html > umami-patch.patch
|
更新主题后应用补丁：
1
2
| # 更新主题后应用补丁
git apply umami-patch.patch
|
安全注意事项
- 保护 Umami 实例：确保你的 Umami 实例受到适当保护，防止未授权访问
- 使用 HTTPS：始终使用 HTTPS 连接你的 Umami 实例
- 限制访问权限：在生产环境中限制对 Umami 管理界面的访问权限
总结
通过以上步骤，我们成功地为 Hugo Next 主题添加了 Umami 统计支持。这种方法不会修改主题的核心文件，因此在主题更新时不会丢失自定义功能。
Umami 提供了一个轻量级、注重隐私的统计解决方案，特别适合注重用户隐私的网站。通过自定义 analytics 文件和修改主题配置，我们可以灵活地集成各种统计工具，满足不同的需求。
这种方法可以应用于其他类似的统计工具，只需相应地修改脚本标签即可。希望这篇指南对你有所帮助，让你的网站能够更好地了解访问者行为，同时保护他们的隐私。
