为Hugo Next主题添加Umami统计支持

发表于： 2026-01-07 分类于：建站相关

字数： 2421 阅读：≈ 5分钟浏览：评论：

温馨提醒

总结摘要

本文详细介绍如何为Hugo Next主题添加开源统计工具Umami的支持。通过自定义analytics文件和修改主题配置，实现对开源统计工具Umami的完整集成。文章涵盖了实现原理、具体步骤、配置方法和验证过程，为使用Hugo博客的用户提供了完整的Umami集成解决方案。

为Hugo Next主题添加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 实例中创建网站时获得的 ID
https://your-umami-instance.com/script.js：你的 Umami 实例的追踪脚本 URL

验证集成

完成上述步骤后，重新构建并启动你的 Hugo 网站：

`1`	`hugo server`

要验证集成是否成功，可以执行以下操作：

打开浏览器，访问你的网站
右键点击页面，选择"查看页面源代码"
搜索页面源代码中是否包含 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 文件和修改主题配置，我们可以灵活地集成各种统计工具，满足不同的需求。

这种方法可以应用于其他类似的统计工具，只需相应地修改脚本标签即可。希望这篇指南对你有所帮助，让你的网站能够更好地了解访问者行为，同时保护他们的隐私。