Hugo GA4 Pageviews

为 Hugo 博客提供 Google Analytics 4 实时页面浏览量统计

通过 Cloudflare Workers 边缘计算，从 Google Analytics 4 API 获取真实的页面浏览量数据，为你的 Hugo 博客添加实时浏览量展示功能。

✨ 特性

• ✅ 真实数据 - 直接从 Google Analytics 4 Data API 获取准确浏览量
• ✅ 边缘计算 - Cloudflare Workers 全球 CDN，毫秒级响应
• ✅ 智能缓存 - 5 分钟缓存策略，大幅节省 API 配额
• ✅ 免费部署 - Cloudflare 免费计划提供 100,000 请求/天
• ✅ CORS 安全 - 白名单机制，防止 API 滥用
• ✅ 自动降级 - KV 存储 → Cache API → 本地缓存多级降级
• ✅ 零配置 - 适配任何 Hugo 主题，无需修改主题代码

📊 效果演示

在线演示: geekhuashan.com

🚀 快速开始

前置要求

• Cloudflare 账号（免费计划即可）
• Google Cloud Platform 账号
• 已配置 Google Analytics 4 的网站

1. Clone 项目

git clone https://github.com/geekhuashan/hugo-ga4-pageviews.git
cd hugo-ga4-pageviews
npm install

2. 配置 Google Cloud（详细步骤见下方）

需要创建服务账号并启用 GA4 API：

# 创建项目 → 启用 Analytics Data API → 创建服务账号 → 下载 JSON 密钥

3. 配置 GA4 授权

将服务账号邮箱添加到 GA4：

# GA4 管理后台 → 属性访问权限管理 → 添加服务账号邮箱 → 授予"查看者"权限

4. 部署到 Cloudflare

# 登录 Cloudflare
npx wrangler login

# 设置环境变量
npx wrangler secret put GA4_PROPERTY_ID      # 输入你的 GA4 Property ID
npx wrangler secret put GA4_CREDENTIALS      # 粘贴服务账号 JSON（单行）

# 修改配置文件
vim wrangler.toml  # 修改 name 和 ALLOWED_ORIGINS

# 部署
npx wrangler deploy

5. 前端集成

在你的 Hugo 主题中添加 JavaScript：

// 获取当前页面浏览量
fetch('https://your-worker.workers.dev?path=' + window.location.pathname)
  .then(res => res.json())
  .then(data => {
    document.getElementById('pageviews').textContent = data.views;
  });

完整前端集成示例见 FRONTEND.md

📖 详细文档

🔧 配置指南

• Google Cloud 配置 - 创建服务账号和 API 密钥
• GA4 授权配置 - 添加服务账号权限
• Cloudflare 部署 - Workers 完整部署流程
• 前端集成指南 - Hugo 主题集成示例

📚 进阶功能

• 自定义域名绑定 - 使用你的域名代替 workers.dev
• KV 存储配置 - 启用持久化缓存提升性能
• 监控和告警 - 使用 Cloudflare Analytics 监控 API

🐛 故障排查

• 常见问题 FAQ - 常见错误和解决方案
• 调试指南 - 查看日志和排查问题

📁 项目结构

hugo-ga4-pageviews/
├── pageviews.js          # Workers 主函数（ES Module）
├── wrangler.toml         # Workers 配置文件
├── package.json          # npm 依赖
├── .gitignore            # Git 忽略规则
├── README.md             # 本文件
├── LICENSE               # MIT 许可证
└── docs/                 # 详细文档目录
    ├── GOOGLE-CLOUD-SETUP.md
    ├── GA4-AUTHORIZATION.md
    ├── CLOUDFLARE-DEPLOYMENT.md
    ├── FRONTEND.md
    ├── CUSTOM-DOMAIN.md
    ├── KV-STORAGE.md
    ├── MONITORING.md
    ├── FAQ.md
    └── DEBUGGING.md

🔑 环境变量

通过 wrangler secret 设置（不要写入代码）：

变量	说明	示例
GA4_PROPERTY_ID	GA4 属性 ID	123456789
GA4_CREDENTIALS	Google 服务账号 JSON（单行）	{"type":"service_account",...}

🛠️ 本地开发

# 启动本地开发服务器（需先配置 Secrets）
npx wrangler dev

# 测试 API
curl "http://localhost:8787?path=/test/"

# 查看实时日志
npx wrangler tail

📊 API 使用

请求

GET https://your-worker.workers.dev?path=/article-url/

响应

{
  "path": "/article-url/",
  "views": 1234,
  "updatedAt": "2025-11-12T12:34:56.789Z",
  "cached": false
}

错误响应

{
  "error": "Failed to fetch page views",
  "message": "详细错误信息"
}

🎯 性能优化

• ✅ 5 分钟缓存 - 减少 GA4 API 调用次数
• ✅ 边缘计算 - Cloudflare 全球 300+ 节点
• ✅ 多级降级 - KV → Cache API → 浏览器缓存
• ✅ CORS 白名单 - 防止恶意请求消耗配额

典型延迟：

• 首次请求（无缓存）：~500ms
• 缓存命中：~50ms

💰 成本分析

Cloudflare Workers 免费计划

• 请求数量：100,000 请求/天
• CPU 时间：10ms/请求
• 存储：无限制（使用 Cache API）

对于日访问量 10,000 的博客：

• 每篇文章平均 3 个浏览量请求
• 缓存 5 分钟 = 每天 288 次刷新
• 月成本：¥0（远低于免费额度）

Google Analytics Data API 配额

• 每天：25,000 次请求（免费）
• 每 100 秒：300 次请求

通过缓存机制，每天实际 API 调用 < 1,000 次。

🔒 安全建议

1. 不要提交密钥到 Git

   # 使用 wrangler secret，而不是环境变量文件
   npx wrangler secret put GA4_CREDENTIALS

2. 配置 CORS 白名单

   const ALLOWED_ORIGINS = [
     'https://yourdomain.com',  // 仅允许你的域名
     'http://localhost:1313'     // 本地开发
   ];

3. 限制服务账号权限

   • 仅授予 GA4 "查看者"权限
   • 不要授予编辑或管理权限

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m '添加某功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启 Pull Request

📄 许可证

本项目基于 MIT License 开源。

🙏 致谢

• Cloudflare Workers - 边缘计算平台
• Google Analytics Data API - 数据来源
• Hugo - 静态网站生成器

💬 联系方式

• 项目主页: https://github.com/geekhuashan/hugo-ga4-pageviews
• 问题反馈: 提交 Issue
• 博客示例: geekhuashan.com

---

如果这个项目对你有帮助，欢迎 ⭐️ Star 支持！