名称： ga4-analytics
描述： "Google Analytics 4、Search Console 和 Indexing API 工具包。用于分析网站流量、页面表现、用户画像、实时访客、搜索查询和 SEO 指标。适用于用户要求：检查网站流量、分析页面浏览量、查看流量来源、查看用户画像、获取实时访客数据、检查 Search Console 查询、分析 SEO 表现、请求 URL 重新索引、检查索引状态、比较日期范围、检查跳出率、查看转化数据或获取电商收入。需要一个拥有 GA4 和 Search Console 访问权限的 Google Cloud 服务账号。"

GA4 分析工具包

设置

安装依赖：

cd scripts && npm install

在项目根目录创建 .env 文件以配置凭据：

GA4_PROPERTY_ID=123456789
GA4_CLIENT_EMAIL=service-account@project.iam.gserviceaccount.com
GA4_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
SEARCH_CONSOLE_SITE_URL=https://your-domain.com
GA4_DEFAULT_DATE_RANGE=30d

前提条件：一个已启用 Analytics Data API、Search Console API 和 Indexing API 的 Google Cloud 项目。一个拥有 GA4 属性和 Search Console 访问权限的服务账号。

快速开始

通过从 scripts/src/index.ts 导入来执行函数：

import { siteOverview, searchConsoleOverview } from './scripts/src/index.js';

const overview = await siteOverview('30d');

或直接使用 tsx 运行：

npx tsx scripts/src/index.ts

工作流程模式

每次分析都遵循三个阶段：

1. 分析

运行 API 函数。每次调用都会访问 Google API 并返回结构化数据。

2. 自动保存

所有结果都会自动保存为带时间戳的 JSON 文件到 results/{category}/。文件命名模式：YYYYMMDD_HHMMSS__operation__extra_info.json

3. 总结

分析完成后，读取保存的 JSON 文件并在 results/summaries/ 中创建 Markdown 总结，包含数据表格、趋势和建议。

高级功能

GA4 分析

Search Console

索引

工具

独立 API 函数

如需更精细的控制，可从 API 模块导入特定函数。完整列表（30 多个 API 函数，包含参数、类型和示例）请参阅 references/api-reference.md。

日期范围

所有函数都接受灵活的日期范围格式：

默认值为 "30d"（可通过 .env 中的 GA4_DEFAULT_DATE_RANGE 配置）。

结果存储

结果自动保存到 results/，结构如下：

results/
├── reports/          # GA4 标准报告
├── realtime/         # 实时快照
├── searchconsole/    # Search Console 数据
├── indexing/         # Indexing API 结果
└── summaries/        # 人类可读的 Markdown 总结

管理结果

import { listResults, loadResult, getLatestResult } from './scripts/src/index.js';

// 列出最近的结果
const files = listResults('reports', 10);

// 加载特定结果
const data = loadResult(files[0]);

// 获取某个操作的最新结果
const latest = getLatestResult('reports', 'site_overview');

常用维度和指标

维度

pagePath, pageTitle, sessionSource, sessionMedium, country, deviceCategory, browser, date, eventName, landingPage, newVsReturning

指标

screenPageViews, activeUsers, sessions, newUsers, bounceRate, averageSessionDuration, engagementRate, conversions, totalRevenue, eventCount

使用技巧

1. 指定日期范围 — "过去 7 天" 或 "过去 90 天" 能提供与默认 30 天不同的洞察。
2. 请求总结报告 — 拉取数据后，可要求生成包含表格和洞察的 Markdown 总结。
3. 比较不同时期 — 使用 compareDateRanges() 来发现趋势（例如本月 vs 上月）。
4. 检查实时数据 — liveSnapshot() 显示当前网站上的访客情况。
5. 结合 GA4 与 Search Console — 流量数据加上搜索查询数据，可获得完整图景。