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 分析

搜索控制台

索引

实用工具

单独的API函数

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

日期范围

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

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

结果存储

结果自动保存至results/目录，结构如下：

results/
├── reports/          # GA4 standard reports
├── realtime/         # Real-time snapshots
├── searchconsole/    # Search Console data
├── indexing/         # Indexing API results
└── summaries/        # Human-readable markdown summaries

管理结果

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

// List recent results
const files = listResults('reports', 10);

// Load a specific result
const data = loadResult(files[0]);

// Get most recent result for an operation
const latest = getLatestResult('reports', 'site_overview');

常用维度和指标

维度

页面路径、页面标题、会话来源、会话媒介、国家/地区、设备类别、浏览器,日期,事件名称,着陆页,新访客与回访访客

指标

屏幕浏览量,活跃用户数,会话数,新用户数,跳出率,平均会话时长,参与率,转化次数,总收入,事件计数

提示

1. 指定日期范围— 选择“最近7天”或“最近90天”可提供与默认30天不同的洞察
2. 请求摘要— 提取数据后，可要求生成包含表格和洞察的Markdown格式摘要
3. 对比时段— 使用compareDateRanges()函数识别趋势（例如本月与上月对比）
4. 查看实时数据—liveSnapshot()可显示当前网站访客状态
5. 结合GA4与搜索控制台— 流量数据与搜索查询数据相结合可呈现完整图景