Vercel + Neon 免费部署 Umami，并接入 Hugo

Umami 是一款开源、轻量的网站访问统计工具，可用于查看访问量、来源、设备、地区和页面浏览等数据。本文记录如何使用 Vercel 部署 Umami、使用 Neon 提供 PostgreSQL 数据库，并将跟踪代码接入 Hugo PaperMod。

本文以个人博客和低流量站点为例。Vercel 与 Neon 的免费额度、控制台界面及相关政策可能发生变化，请以官方页面显示为准。

准备工作

开始前需要准备：

  • 一个 GitHub 账号，用于创建 Umami 代码仓库
  • 一个 Vercel 账号，用于部署 Umami
  • 一个可正常访问的 Hugo 网站
  • 可选的自定义域名

部署过程主要分为四步：

  1. 在 Vercel 中创建 Neon PostgreSQL 数据库
  2. 从 Umami 官方仓库创建项目并部署
  3. 登录 Umami，添加需要统计的网站
  4. 将跟踪代码添加到 Hugo 的 <head> 中

创建 Neon 数据库

1. 新建存储服务

进入 Vercel 控制台，点击顶部的 Create New。

在 Vercel 中创建新资源

选择 Storage。

选择 Storage

点击 Create Storage，新建存储服务。

创建 Storage

在数据库类型中选择 Neon。

选择 Neon 数据库

2. 完成数据库配置

根据页面提示确认数据库名称、区域等配置。此时可以暂不关联 Vercel 项目；如果页面要求填写 Custom Prefix，设置一个便于识别的环境变量前缀即可。

配置并创建 Neon 数据库

数据库创建完成后，进入数据库详情页，点击 Open in Neon 打开 Neon 控制台。

从 Vercel 打开 Neon 控制台

3. 获取数据库连接字符串

在 Neon 控制台左上角点击 Connect，打开数据库连接面板。

打开 Neon 数据库连接面板

复制 PostgreSQL 连接字符串，后续需要将它设置为 Umami 的 DATABASE_URL 环境变量。

复制 Neon 数据库连接字符串

连接字符串通常类似：

1

postgresql://username:password@hostname/database?sslmode=require

DATABASE_URL 中包含数据库账号和密码，不要将它写入公开文章、截图、Git 仓库或前端代码。

在 Vercel 部署 Umami

1. 从官方仓库创建项目

打开 Umami 的 Vercel 部署页面，使用 Umami 官方仓库创建 Vercel 项目。

首次部署时，Vercel 会要求在 GitHub 账号下创建一个新的仓库。填写容易辨认的仓库名，例如 umami 或 umami-analytics。

导入 Umami 官方仓库

2. 配置数据库环境变量

在项目配置页面找到环境变量，将刚才复制的 Neon 连接字符串填入：

1

DATABASE_URL=你的 Neon 数据库连接字符串

确认变量名称为 DATABASE_URL，然后点击部署。Vercel 将自动安装依赖、初始化数据库并构建 Umami。

设置 DATABASE_URL 并部署 Umami

部署完成后，打开 Vercel 提供的项目域名。如果能够看到 Umami 登录页面，说明应用和数据库已经连接成功。

3. 首次登录并修改密码

首次登录可尝试使用 Umami 的默认管理员账号：

1
2

用户名：admin
密码：umami

Umami 登录页面

登录后应立即进入个人资料或账号设置，修改默认密码。默认凭据是公开信息，长期保留会带来账号被接管的风险。

如果默认账号无法登录，请查看 Vercel 的部署日志，并参考当前版本的 Umami 官方文档；不同版本的初始化流程可能有所变化。

在 Umami 中添加网站

进入 Umami 后，在网站管理页面点击添加网站，填写站点名称和域名。

在 Umami 中添加网站

域名只需填写主机名，一般不包含协议和路径。例如：

1

blogs.nyanx.de

网站创建完成后，进入对应网站，点击右上角的 Edit 或相关设置按钮。

打开 Umami 网站设置

在跟踪代码页面复制 Umami 生成的 <script> 标签。

复制 Umami 跟踪代码

自托管 Umami 生成的代码通常类似：

1

<script defer src="https://你的-umami-域名/script.js" data-website-id="你的网站 ID"></script>

如果使用 Umami Cloud，则脚本地址通常为：

1

<script defer src="https://cloud.umami.is/script.js" data-website-id="你的网站 ID"></script>

data-website-id 必须使用当前网站对应的 ID，不要直接照抄其他站点的示例值。

将 Umami 接入 Hugo PaperMod

PaperMod 会自动加载 layouts/partials/extend_head.html 中的自定义内容，因此不需要直接修改主题目录。

在 Hugo 项目根目录创建以下文件：

1

layouts/partials/extend_head.html

如果 layouts 或 partials 目录不存在，按上述层级手动创建。然后将 Umami 提供的完整跟踪代码粘贴到文件中：

1

<script defer src="https://你的-umami-域名/script.js" data-website-id="你的网站 ID"></script>

在 extend_head.html 中添加 Umami 跟踪代码

保存后重新构建并部署 Hugo 网站。不要修改 themes/PaperMod 中的同名文件，否则主题更新时改动可能被覆盖。

如果 extend_head.html 中已经存在字体、验证标签或其他代码，保留原内容并另起一行加入 Umami 脚本即可。请确保同一个网站只加载一次跟踪脚本，以免造成重复统计。

验证统计是否生效

网站部署完成后，可以按以下步骤检查：

  1. 打开已部署的网站并访问几个页面
  2. 在浏览器中按 F12 打开开发者工具
  3. 进入 Network 面板并刷新页面
  4. 搜索 script.js，确认跟踪脚本返回 200
  5. 搜索 api/send，确认统计请求已成功发出
  6. 返回 Umami 控制台，等待片刻后查看实时访客或页面浏览数据

也可以在页面源代码中搜索 data-website-id，确认跟踪代码已经进入网页的 <head>。

常见问题

部署后出现数据库连接错误

重点检查以下内容：

  • Vercel 中是否存在名为 DATABASE_URL 的环境变量
  • 连接字符串是否完整，复制时有没有遗漏字符
  • Neon 数据库是否处于可用状态
  • 数据库连接是否要求 SSL
  • 修改环境变量后是否重新部署了项目

Umami 页面可以打开，但没有统计数据

可以依次检查：

  • data-website-id 是否属于当前网站
  • 跟踪脚本域名是否可以正常访问
  • 网站是否已重新构建并部署
  • 浏览器广告拦截插件是否拦截了统计请求
  • Umami 中填写的网站域名是否正确
  • 页面是否重复加载了多个 Umami 脚本

Vercel 部署失败

进入 Vercel 项目的 Deployments 页面查看构建日志。常见原因包括数据库连接失败、环境变量缺失、上游 Umami 版本更新，或免费套餐限制发生变化。

自定义域名后统计失效

为 Umami 绑定新域名后，需要同步更新 Hugo 中脚本的 src 地址，并确认 HTTPS 证书已经生效。如果 Umami 网站配置中启用了域名限制，也要将博客的新域名更新进去。

后续维护建议

  • 定期更新 Umami，部署前先阅读版本升级说明
  • 定期检查 Neon 和 Vercel 的用量及免费额度政策
  • 妥善保管 DATABASE_URL，发现泄露后及时轮换数据库密码
  • 为 Umami 管理后台设置强密码，不再使用默认凭据
  • 绑定自定义域名时启用 HTTPS
  • 重大升级前备份 PostgreSQL 数据库

完成以上配置后，Hugo 网站的访问数据就会发送到自己的 Umami 实例中，可以在不依赖传统大型统计平台的情况下查看基础访问情况。