GA4 Analytics Toolkit 是一个整合 Google Analytics 4、Search Console 与 Indexing API 的分析工具包，帮助用户以脚本方式获取网站流量、页面表现、用户画像、实时访客和搜索查询等数据。
用途 该工具包面向需要定期分析网站数据、SEO 表现和索引状态的用户。它把 GA4 报告、Search Console 数据和 Indexing API 操作封装为可调用的 TypeScript 函数，适合在本地或自动化流程中运行。
主要能力 工具包提供高层函数和底层 API 函数两类接口。高层函数包括：siteOverview（站点综合快照，含页面浏览量、流量来源、用户画像、事件）、trafficAnalysis（流量深入分析，含来源、按来源/媒介划分的会话、新老访客）、contentPerformance（热门页面分析，含页面浏览量、落地页、退出页）、userBehavior（互动模式，含用户画像、事件、每日互动指标）、compareDateRanges（两个日期范围的并排对比）、liveSnapshot（实时数据，含活跃用户、当前页面、当前事件）。Search Console 相关函数包括：searchConsoleOverview（SEO 快照，含热门查询、页面、设备、国家分布）、keywordAnalysis（关键词深入分析，含按设备划分的查询）、seoPagePerformance（页面 SEO 指标，含按点击量排序的热门页面、国家分布）。Indexing 相关函数包括：reindexUrls（请求重新索引多个 URL）、checkIndexStatus（检查 URL 是否已被索引）。此外还有 getAvailableFields 用于列出所有可用的 GA4 维度和指标。底层 API 模块提供 30 多个细粒度函数，具体参数、类型和示例见 references/api-reference.md。
使用方式 安装依赖：cd scripts && npm install。在项目根目录创建 .env 文件配置凭据，包括 GA4_PROPERTY_ID、GA4_CLIENT_EMAIL、GA4_PRIVATE_KEY、SEARCH_CONSOLE_SITE_URL、GA4_DEFAULT_DATE_RANGE。前置条件：一个启用了 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'，然后 await siteOverview('30d')；也可用 npx tsx scripts/src/index.ts 直接运行。日期范围支持简写（"7d"、"30d"、"90d"）、显式日期（{startDate: "2024-01-01", endDate: "2024-01-31"}）和 GA4 相对格式（{startDate: "30daysAgo", endDate: "today"}），默认 "30d"，可通过 .env 中的 GA4_DEFAULT_DATE_RANGE 配置。
工作流程 每次分析遵循三个阶段：分析（运行 API 函数，返回结构化数据）、自动保存（所有结果自动保存为带时间戳的 JSON 文件到 results/{category}/，命名格式为 YYYYMMDD_HHMMSS__operation__extra_info.json）、总结（读取保存的 JSON 文件，在 results/summaries/ 生成含数据表格、趋势和建议的 Markdown 摘要）。结果目录结构包括 reports（GA4 标准报告）、realtime（实时快照）、searchconsole（Search Console 数据）、indexing（Indexing API 结果）、summaries（可读的 Markdown 摘要）。可用 listResults、loadResult、getLatestResult 管理结果。
常用维度与指标 维度包括 pagePath、pageTitle、sessionSource、sessionMedium、country、deviceCategory、browser、date、eventName、landingPage、newVsReturning。指标包括 screenPageViews、activeUsers、sessions、newUsers、bounceRate、averageSessionDuration、engagementRate、conversions、totalRevenue、eventCount。
适用场景 适合需要定期查看网站流量趋势、分析热门页面、研究搜索关键词、对比不同时间段表现、监控实时访客，以及批量提交 URL 重新索引的场景。
限制 使用前必须完成 Google Cloud 项目配置、API 启用和服务账号授权，否则无法调用。工具依赖 Google 官方 API 的配额与权限。关于收费、价格、平台支持范围等具体信息，资料中暂未提供。