myblog/docs/百度统计集成使用说明.md

百度统计集成使用说明

概述

本项目已集成百度统计 API，可以实时获取文章的浏览量(PV)和访客量(UV)数据，并在页面中展示。

功能特性

• ✅ 实时获取百度统计数据
• ✅ 文章页面显示浏览量和访客量
• ✅ 统计数据管理页面
• ✅ 数据缓存机制（5分钟缓存）
• ✅ 自动刷新功能
• ✅ 数据导出功能
• ✅ 响应式设计

配置说明

1. 配置文件位置

src/config/analytics.ts

2. 主要配置项

export const BAIDU_ANALYTICS_CONFIG = {
  // 访问令牌 - 需要定期更新
  accessToken: 'your_access_token_here',
  
  // 站点 ID
  siteId: 'your_site_id_here',
  
  // 百度统计站点代码
  siteCode: 'your_site_code_here',
  
  // 缓存配置
  cache: {
    expiry: 5 * 60 * 1000, // 5分钟缓存
  }
};

3. 环境变量配置（可选）

在 .env 文件中设置：

VITE_BAIDU_ACCESS_TOKEN=your_access_token
VITE_BAIDU_SITE_ID=your_site_id
VITE_BAIDU_SITE_CODE=your_site_code

使用方法

1. 在文章页面显示统计数据

import { ArticleStatsDisplay } from '@/components/blog/stats-display';

// 在文章组件中使用
<ArticleStatsDisplay 
  articleSlug="your-article-slug" 
  variant="inline" // 或 "card", "badge"
/>

2. 显示总体统计数据

import { TotalStatsDisplay } from '@/components/blog/stats-display';

// 显示网站总体统计
<TotalStatsDisplay variant="card" />

3. 使用 Hook 获取数据

import { useBaiduAnalytics, useArticleStats } from '@/hooks/use-baidu-analytics';

// 获取所有统计数据
const { articleStats, totalStats, loading, error } = useBaiduAnalytics();

// 获取单个文章统计
const { stats, loading, error } = useArticleStats('article-slug');

页面功能

1. 文章详情页

• 在文章元信息区域显示该文章的浏览量和访客量
• 数据来源：百度统计 API
• 自动匹配文章 URL

2. 统计管理页面 (/analytics)

• 查看所有文章的统计数据
• 支持时间范围筛选（今天、最近7天、最近30天、全部时间）
• 数据导出功能（CSV格式）
• 实时刷新功能

API 接口说明

百度统计 API 端点

GET https://openapi.baidu.com/rest/2.0/tongji/report/getData

请求参数

• access_token: 访问令牌
• site_id: 站点ID
• method: visit/toppage/a（受访页面报告）
• metrics: pv_count,visitor_count（浏览量和访客数）
• start_date: 开始日期（可选）
• end_date: 结束日期（可选）

响应数据格式

{
  "result": {
    "items": [
      [
        [{"name": "页面URL", "pageId": "页面ID"}],
        [浏览量, 访客数]
      ]
    ]
  }
}

数据匹配逻辑

系统通过以下方式匹配文章和统计数据：

1. URL 匹配: 检查页面 URL 是否包含 /article/{articleSlug}
2. 文章 slug 匹配: 从 URL 中提取文章标识符
3. 模糊匹配: 支持 URL 编码的中文标题匹配

缓存机制

• 缓存时间: 5分钟
• 缓存策略: 内存缓存，页面刷新后清空
• 自动刷新: 可配置自动刷新间隔

错误处理

• API 请求失败时显示友好错误信息
• 网络错误时使用缓存数据
• 数据解析错误时返回空结果

性能优化

• 数据缓存减少 API 调用
• 懒加载统计组件
• 并行请求多个数据源
• 防抖处理频繁刷新

注意事项

1. Access Token 更新: 百度统计的 access_token 有有效期，需要定期更新
2. API 限制: 百度统计 API 有调用频率限制，建议合理使用缓存
3. 数据延迟: 百度统计数据可能有1-2小时的延迟
4. URL 匹配: 确保文章 URL 格式与百度统计中的页面 URL 一致

故障排除

1. 数据不显示

• 检查 access_token 是否有效
• 确认 site_id 是否正确
• 查看浏览器控制台错误信息

2. 数据不匹配

• 检查文章 URL 格式
• 确认百度统计是否正确跟踪页面
• 查看 API 返回的页面列表

3. 性能问题

• 调整缓存时间
• 减少自动刷新频率
• 检查网络连接

更新日志

• v1.0.0 (2025-09-23): 初始版本，支持基础统计功能
  • 百度统计 API 集成
  • 文章统计显示组件
  • 统计管理页面
  • 数据缓存和自动刷新