Umami访问量统计配置说明
约 771 字大约 3 分钟
2025-10-20
Umami 是一个开源、注重隐私的网站分析工具,可以替代 Google Analytics。本教程将指导您如何在 Mizuki 主题中配置 Umami 统计功能。
注意:本教程适用于 Mizuki 5.1.0 或更高版本。
什么是 Umami?
Umami 是一个开源的网站分析工具,具有以下特点:
- 开源且注重用户隐私
- 轻量级,不会影响网站性能
- 提供详细的访问统计信息
- 可自建服务或使用云服务
配置步骤
1. 注册并创建 Umami 账户
首先,您需要注册一个 Umami 账户:
- 访问 Umami 官网 或使用自建的 Umami 服务(V3版本暂时没开源)
- 注册账户并登录
- 创建一个新的网站,获取网站ID
2. 获取必要信息
在 Umami 仪表板中,您需要获取以下信息:
- API 密钥 (API Key)
- 网站ID (Website ID)
- 跟踪脚本地址 (Tracking Script URL)
3. 配置 Mizuki
打开 src/config.ts 文件,找到 umamiConfig 配置项:
export const umamiConfig = {
enabled: false, // 是否启用 Umami 统计
apiKey: "api_XXXXXXXXXX", // 你的 API 密钥
baseUrl: "https://api.umami.is", // Umami Cloud API 地址
scripts: `
<script defer src="XXXX.XXX" data-website-id="ABCD1234"></script>
`.trim(), // 上面填你要插入的 Script,不用再去 Layout 中插入
} as const;4. 修改配置参数
根据您的 Umami 账户信息,修改以下参数:
enabled
设置为 true 以启用 Umami 统计功能:
enabled: true,apiKey
替换为您的实际 API 密钥:
apiKey: "your_actual_api_key_here",baseUrl
如果您使用 Umami Cloud,保持默认值;如果使用自建服务,请替换为您的服务地址:
baseUrl: "https://api.umami.is", // Umami Cloud
// 或者
baseUrl: "https://your-umami-instance.com", // 自建服务scripts
替换为您的实际跟踪脚本,包含您的网站ID:
scripts: `
<script defer src="https://analytics.umami.is/script.js" data-website-id="your_website_id_here"></script>
`.trim(),5. 完整配置示例
以下是一个完整的配置示例:
export const umamiConfig = {
enabled: true,
apiKey: "api_a1b2c3d4e5f6g7h8i9j0",
baseUrl: "https://api.umami.is",
scripts: `
<script defer src="https://analytics.umami.is/script.js" data-website-id="abcd1234-ef56-7890-abcd-ef1234567890"></script>
`.trim(),
} as const;6. 保存并重新构建
- 保存
src/config.ts文件 - 重新构建您的网站:
pnpm build - 部署您的网站
验证配置
配置完成后,您可以通过以下方式验证是否配置成功:
- 访问您的网站
- 打开浏览器开发者工具
- 查看网络请求,确认是否有发送到 Umami 服务器的请求
- 在 Umami 仪表板中查看实时访问数据
故障排除
如果配置后没有数据,请检查:
- 确认 enabled 设置为 true
- 检查 API 密钥是否正确
- 确认网站ID是否正确
- 检查跟踪脚本地址是否正确
- 查看浏览器控制台是否有错误信息
- 确认 Umami 服务是否正常运行
隐私保护
Umami 重视用户隐私,不会收集个人身份信息。您可以在您的隐私政策中添加 Umami 的使用说明,以确保透明度。