命令行工具 analytics-cli：自动化获取GA4与GSC数据，集成AI与CI/CD

1. 项目概述与核心价值

如果你和我一样，日常工作中需要频繁查看 Google Analytics 4 (GA4) 和 Google Search Console (GSC) 的数据，但又厌倦了在浏览器里反复点击、筛选、导出的繁琐流程，那么analytics-cli这个工具的出现，绝对能让你眼前一亮。它本质上是一个命令行工具，让你能像在终端里执行ls或grep一样，直接获取网站的分析数据。这个项目最初的设计动机，是为了替代 Cursor 编辑器中的 MCP（Model Context Protocol）服务器，提供一个更轻量、更直接、不依赖特定 IDE 的数据获取方案。

简单来说，它解决了几个核心痛点：自动化、脚本化和集成化。想象一下，你不再需要每天手动登录后台截图，而是写一个简单的 Shell 脚本，定时运行analytics-cli命令，就能把昨天的关键指标自动发到你的团队 Slack 频道或生成日报。或者，当你正在用 Cursor 进行 AI 编程时，可以直接在聊天框里问：“上个月流量最高的页面是哪些？”，AI 会通过集成的 Skill 自动调用这个 CLI 来获取答案，实现真正的“对话式数据分析”。

这个工具的核心用户，是那些需要将数据分析流程嵌入到自动化脚本、CI/CD 流水线，或者希望与 AI 助手深度集成的开发者、运维和增长工程师。它不追求替代 GA4 或 GSC 的完整后台，而是专注于成为一个高效、可靠的数据“管道”，让你能用程序员最熟悉的方式——命令行，来操控你的业务数据。

2. 核心设计思路与架构解析

2.1 为什么选择 CLI 而非 GUI 或 SDK？

analytics-cli选择命令行接口作为主要形态，背后有非常务实的考量。首先，可编程性是 CLI 的天然优势。任何命令行输出都可以通过管道 (|) 传递给grep,awk,jq等工具进行二次处理，或者直接写入文件、发送 HTTP 请求，无缝融入现有的自动化生态。其次，资源消耗极低。它不需要运行一个常驻的图形界面或 Web 服务器，仅在执行命令时调用 Google API，获取数据后立即退出，对系统资源非常友好。最后，环境一致性。无论是在本地开发机、远程服务器还是 Docker 容器中，CLI 的运行方式都是一致的，避免了 GUI 工具因操作系统或桌面环境不同带来的兼容性问题。

项目的架构非常清晰，遵循了 Unix 哲学中的“只做一件事，并做好”的原则。它本质上是一个 Node.js 脚本的封装，核心依赖是 Google 官方提供的googleapisnpm 库。整个工具没有复杂的中间层，你的命令参数经过解析后，直接转换为对应 Google API（Analytics Data API v1beta 和 Search Console API v1）的请求，拿到数据后按指定格式（Markdown 或 JSON）渲染输出。这种“短路径”设计，使得它响应迅速，也更容易调试和维护。

2.2 多项目凭证管理策略

一个非常巧妙且实用的设计是它的凭证管理策略。与许多工具要求你将服务账号的 JSON 密钥文件放在某个固定目录不同，analytics-cli从当前工作目录读取.env.local或.env文件。这意味着你可以在不同的项目文件夹下放置不同的.env.local文件，每个文件对应一个 GA4 媒体资源或 GSC 站点。

例如，你的文件结构可能是这样的：

~/projects/client-a/ ├── .env.local # 配置 client-a 网站的 GA_VIEW_ID 和密钥 └── run-report.sh ~/projects/client-b/ ├── .env.local # 配置 client-b 网站的 GA_VIEW_ID 和密钥 └── run-report.sh

当你进入~/projects/client-a/并执行命令时，工具会自动读取该目录下的凭证去查询 client-a 的数据。这种设计完美支持了代理公司、自由职业者或管理多个产品的团队场景，无需在每次切换项目时修改全局配置或传递复杂的参数。

2.3 与 Cursor AI 的深度集成逻辑

项目中提到的 Cursor Agent Skill 是其“AI友好”特性的关键体现。Cursor 编辑器允许开发者创建“技能”（Skills），这些技能本质上是告诉 Cursor 的 AI 助手：“当用户提出某类需求时，你可以执行某个特定的命令或函数来获取信息”。analytics-cli提供的 Skill 文件 (SKILL.md) 就包含了这样的指令映射。

其工作原理是：当你向 Cursor 的 AI 提问关于网站流量的问题时，AI 会识别出你的意图，然后根据 Skill 的定义，在后台自动执行相应的npx analytics-cli ...命令，并将命令的输出结果作为上下文反馈给你。这相当于为你的 AI 助手装上了直接访问真实业务数据的“眼睛”，使其回答不再是基于过时的通用知识，而是基于你网站的最新表现。这种集成方式代表了未来开发工具的一个趋势：AI 不再是孤立的聊天机器人，而是能主动操作工具、获取实时数据的工作伙伴。

3. 从零开始的完整部署与配置指南

3.1 环境准备与工具安装

首先，确保你的系统已经安装了Node.js 18 或更高版本。你可以通过node --version来检查。接下来，安装analytics-cli。根据项目文档，最推荐的方式是从 GitHub 直接安装，这样能确保你获取到最新的代码。

# 进入你的项目目录（这里将存放你的 .env.local 文件） cd /path/to/your-project-directory # 从 GitHub 安装 analytics-cli npm install github:kasdimg/analytics-cli

安装完成后，你会在node_modules目录下找到这个工具。此时，你可以通过npx来运行它。npx是 npm 自带的工具，用于执行本地安装的包中的命令，无需全局安装。

注意：我强烈建议采用这种“项目本地安装”的方式，而不是npm install -g全局安装。理由有三：第一，避免不同项目因全局包版本冲突导致的问题；第二，符合其“凭证基于当前目录”的设计哲学；第三，便于在package.json的scripts中定义专属的分析命令。

3.2 服务账号创建与权限配置详解

这是整个配置过程中最关键、也最容易出错的一步。你需要一个 Google Cloud 服务账号来代表你的程序访问 GA4 和 GSC 数据。

第一步：在 Google Cloud Console 创建服务账号

1. 访问 Google Cloud Console 。
2. 选择或创建一个项目（这个项目只是一个用于管理 API 和凭证的容器，不一定是你网站所在的 GCP 项目）。
3. 导航到IAM 和管理 > 服务账号。
4. 点击“创建服务账号”，输入一个易于识别的名称（如analytics-cli-sa），然后点击“创建并继续”。
5. 在“授予此服务账号对项目的访问权限”步骤，暂时不需要添加任何角色，直接点击“继续”，然后“完成”。角色我们将在下一步针对具体 API 授予。

第二步：创建并下载 JSON 密钥

1. 在刚创建的服务账号列表中，找到该账号，点击其右侧的“操作”菜单（三个点），选择“管理密钥”。
2. 点击“添加密钥” > “创建新密钥”。
3. 密钥类型选择JSON，然后点击“创建”。浏览器会自动下载一个包含私钥的 JSON 文件（如your-project-abc123.json）。请务必妥善保管此文件，它相当于最高权限的密码。

第三步：提取并格式化环境变量打开下载的 JSON 文件，你会看到如下内容：

{ "type": "service_account", "project_id": "...", "private_key_id": "...", "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCq...\n-----END PRIVATE KEY-----\n", "client_email": "analytics-cli-sa@your-project.iam.gserviceaccount.com", "client_id": "...", "auth_uri": "...", "token_uri": "...", "auth_provider_x509_cert_url": "...", "client_x509_cert_url": "..." }

你需要的是client_email和private_key这两个字段的值。注意，private_key的值是一个包含换行符\n的长字符串。

第四步：配置 GA4 访问权限

1. 在 Google Cloud Console 中，为你当前的项目启用Google Analytics Data API。
2. 登录到你的 Google Analytics 4 后台。
3. 进入“管理”（左下角齿轮图标）> “媒体资源”列下的“媒体资源访问权限管理”。
4. 点击“+” > “添加用户”。
5. 在“电子邮件地址”栏中，填入你 JSON 文件中的client_email（即服务账号邮箱）。
6. 角色选择查看者。对于 CLI 工具只读获取数据来说，这个权限足够了。
7. 点击“添加”。现在这个服务账号就有权读取该 GA4 媒体资源的数据了。你需要知道该媒体资源的数字 ID（即GA_VIEW_ID）。你可以在“管理” > “媒体资源设置”中，找到“媒体资源 ID”，它是一串数字。

第五步：配置 Search Console 访问权限

1. 在 Google Cloud Console 中，同样为你的项目启用Google Search Console API。
2. 登录到你的 Google Search Console 。
3. 选择你要管理的网站属性。
4. 点击左侧“设置” > “用户和权限”。
5. 点击“添加用户”。
6. 同样填入服务账号的client_email。
7. 权限选择“受限”（实际上，对于 API 访问，“完全”权限通常不是必须的，“受限”即可提供数据读取权限，但为确保无误，可以先尝试“完全”，如果 API 调用失败再调整）。
8. 点击“添加”。

3.3 环境变量文件 (.env.local) 的创建与安全实践

在项目的根目录下，复制示例环境文件并开始配置：

cp node_modules/analytics-cli/.env.example .env.local

用文本编辑器打开.env.local，填入你的信息。这里有一个至关重要的细节：GA_PRIVATE_KEY的值必须保留 JSON 文件中的原始格式，包括-----BEGIN PRIVATE KEY-----\n和\n-----END PRIVATE KEY-----\n以及中间所有的\n换行符。许多新手会在这里出错，手动删除换行符或格式错误导致认证失败。

一个正确的.env.local示例：

GA_CLIENT_EMAIL=analytics-cli-sa@your-project-123456.iam.gserviceaccount.com GA_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCq...（此处是长长的密钥）...\n-----END PRIVATE KEY-----\n" GA_VIEW_ID=3456789012

安全警告：.env.local文件包含了你的服务账号私钥，绝对不要将其提交到 Git 等版本控制系统。确保它在.gitignore文件中。一个最佳实践是：将.env.example提交到仓库作为模板，而.env.local永远留在本地。在团队协作时，通过安全的密码管理工具（如 1Password, Bitwarden）或云服务提供的 Secrets Manager 来分享这些敏感信息。

如果你的 GA4 和 Search Console 使用同一个服务账号（大多数情况下推荐这样做，便于管理），那么配置到此就结束了。如果需要为 GSC 使用独立的服务账号，才需要额外设置GSC_CLIENT_EMAIL和GSC_PRIVATE_KEY。

4. 核心命令实战与高级用法

4.1 GA4 数据查询全解析

analytics-cli为 GA4 提供了几个最常用的报告命令。让我们深入每个命令的参数和实际应用场景。

基础报告 (ga4 report)这是最灵活的命令，允许你指定维度来查看指标。

# 查看2024年第四季度，按日期汇总的会话数和用户数 npx analytics-cli ga4 report --start 2024-10-01 --end 2024-12-31 --dimensions date

输出会是 Markdown 表格，包含日期、活跃用户、会话数等。--dimensions参数是这里的灵魂，它决定了数据如何切片。除了date，你还可以尝试：

• pagePath: 查看哪个页面最受欢迎。
• deviceCategory: 分析桌面、移动、平板设备的流量分布。
• country: 了解用户的地理来源。
• sessionDefaultChannelGroup: 分析流量来源（自然搜索、直接访问、社交媒体等）。

页面浏览量 (ga4 page-views)这个命令是ga4 report --dimensions date在页面浏览量指标上的一个快捷方式，输出更简洁。

# 获取最近30天的每日页面浏览量 npx analytics-cli ga4 page-views --start $(date -v-30d +%Y-%m-%d) --end $(date +%Y-%m-%d)

这里用到了date命令（macOS）来自动计算日期，在 Linux 上可能是date --date="30 days ago" +%Y-%m-%d。这个技巧对于编写每日/每周自动运行的脚本非常有用。

活跃用户 (ga4 active-users)与page-views类似，这是查看日活跃用户（DAU）趋势的快捷命令。

# 以JSON格式输出本月至今的活跃用户数据，便于其他程序解析 npx analytics-cli ga4 active-users --start 2025-04-01 --end 2025-04-15 --output json

当你需要将数据导入到 Grafana、Metabase 等数据可视化工具，或者用 Python/Pandas 做进一步分析时，--output json选项就派上用场了。

事件分析 (ga4 events)GA4 的核心是事件驱动模型。这个命令帮你快速查看指定时间段内，各个事件被触发的次数。

# 查看上周发生的所有事件及其计数 npx analytics-cli ga4 events --start $(date -v-7d +%Y-%m-%d) --end $(date +%Y-%m-%d)

这对于监控关键用户行为（如purchase,sign_up,click）非常有效。你可以基于此快速判断新上线的功能或按钮的受欢迎程度。

4.2 Search Console 数据深度挖掘

Search Console 数据对于 SEO 工作至关重要。gsc search-analytics命令让你能直接获取这些数据。

必需参数--site这是最容易出错的地方。--site参数的值必须与你 Search Console 中属性的“网址”格式完全一致。主要有两种格式：

• 网域属性（推荐）：如果你验证的是整个域名（如example.com），则格式为sc-domain:example.com。
• 网址前缀属性：如果你验证的是带协议的完整 URL（如https://www.example.com/），则直接使用该 URL。

你可以通过以下命令快速测试你的站点格式是否正确：

# 尝试网域属性格式 npx analytics-cli gsc search-analytics --site "sc-domain:yourdomain.com" --start 2025-01-01 --end 2025-01-02 --dimensions query --row-limit 1 # 尝试网址前缀属性格式 npx analytics-cli gsc search-analytics --site "https://www.yourdomain.com/" --start 2025-01-01 --end 2025-01-02 --dimensions query --row-limit 1

哪个命令能成功返回数据（哪怕只有一行），就说明哪个格式是正确的。

多维度组合分析Search Console API 的强大之处在于可以组合多个维度。--dimensions参数可以接受逗号分隔的多个值。

# 分析不同设备上，带来最多点击的搜索查询和落地页分别是哪些 npx analytics-cli gsc search-analytics \ --site "sc-domain:example.com" \ --start 2025-03-01 --end 2025-03-31 \ --dimensions query,page,device \ --row-limit 500

这个命令的结果表格会包含“查询词”、“着陆页”、“设备”以及对应的“点击次数”、“展示次数”、“平均排名”和“点击率”。这对于进行精细化的 SEO 内容优化和设备适配策略制定极具价值。

处理大量数据 (--row-limit)默认情况下，GSC 命令最多返回 1000 行数据。对于大型网站，你可能需要增加这个限制。但请注意，Google API 对单次请求返回的数据量有上限，并且请求大量数据可能需要更长时间。一个更稳健的策略是分日期范围多次查询，然后合并结果。

4.3 输出控制与自动化集成

格式化输出

• --output md: 生成美观的 Markdown 表格，适合直接粘贴到文档或 Notion 中。
• --output json: 生成结构化的 JSON，是后续程序化处理的首选。

输出到文件使用--out-file参数可以将结果直接保存到文件，这对于生成定期报告至关重要。

# 生成一份上周的GA4核心指标报告 npx analytics-cli ga4 report --start $(date -v-7d +%Y-%m-%d) --end $(date +%Y-%m-%d) --dimensions date --out-file ./reports/last_week_ga4_report.md # 生成一份上月的SEO表现报告（JSON格式） npx analytics-cli gsc search-analytics --site "sc-domain:example.com" --start $(date -v-1m +%Y-%m-01) --end $(date +%Y-%m-%d) --dimensions query,page --row-limit 2000 --output json --out-file ./reports/$(date +%Y-%m)_seo_data.json

与 Cron 或 CI/CD 集成你可以轻松地创建 Shell 脚本，并结合系统的定时任务（如 Linux 的 cron 或 macOS 的 launchd）来实现日报、周报的自动生成。

#!/bin/bash # 文件：~/scripts/daily_analytics.sh REPORT_DIR="$HOME/analytics_reports" mkdir -p $REPORT_DIR # 获取昨天日期 YESTERDAY=$(date -v-1d +%Y-%m-%d) # 切换到项目目录，这里会读取对应的 .env.local cd /path/to/your-project # 运行GA4报告 npx analytics-cli ga4 report --start $YESTERDAY --end $YESTERDAY --dimensions pagePath --out-file $REPORT_DIR/ga4_$YESTERDAY.md # 运行GSC报告 npx analytics-cli gsc search-analytics --site "sc-domain:example.com" --start $YESTERDAY --end $YESTERDAY --dimensions query --out-file $REPORT_DIR/gsc_$YESTERDAY.md echo "每日报告已生成于 $REPORT_DIR"

然后，通过crontab -e添加一行，让这个脚本每天凌晨运行：

0 2 * * * /bin/bash ~/scripts/daily_analytics.sh > /tmp/analytics_cron.log 2>&1

5. 进阶技巧、疑难排查与性能优化

5.1 利用 Cursor Skill 实现自然语言数据分析

配置 Cursor Skill 后，你的数据分析工作流会发生质变。假设你已经按照文档将 Skill 复制或链接到了~/.cursor/skills/目录下。

实战对话示例：

• 你：“对比一下本周和上周的页面浏览量趋势。”
• Cursor AI：（识别意图）-> （在后台执行类似npx analytics-cli ga4 page-views --start 2025-04-08 --end 2025-04-14和... --start 2025-04-01 --end 2025-04-07的命令）-> （获取结果并对比）-> （用自然语言向你汇报趋势变化，并附上数据表格）。

Skill 的自定义与增强：项目自带的SKILL.md是一个起点。你可以根据团队的需求对其进行增强。例如，你可以定义更复杂的技能，让 AI 不仅能获取数据，还能进行简单的计算，比如“计算一下本月至今的平均会话时长”或“找出点击率低于1%但展示量超过1000的关键词”。这需要你在 Skill 描述中更精确地定义 AI 应该执行的命令序列和数据处理逻辑。

5.2 常见错误与解决方案速查表

在实际使用中，你可能会遇到以下问题。这里是一个快速排查指南：

5.3 性能优化与最佳实践

1. 合理控制查询日期范围：避免一次性查询过长时间范围（如一整年）的高维度数据（如query,page,device）。这可能导致 API 响应缓慢甚至超时。对于历史数据拉取，建议按周或按月分批查询。

2. 使用缓存减少 API 调用：如果你需要频繁查询相同的数据（例如，仪表盘每5分钟刷新），可以考虑在脚本层面加入简单的缓存机制。例如，将查询结果按参数哈希后保存到本地文件，并在短时间内重复查询时直接读取缓存文件。

3. 将 CLI 集成到更大的数据管道中：analytics-cli非常适合作为数据提取（Extract）环节的工具。你可以编写一个脚本，定期运行它获取 JSON 数据，然后使用 Python (pandas)、R 或甚至jq进行转换（Transform），最后加载（Load）到数据库（如 PostgreSQL、BigQuery）或数据仓库中，供更复杂的 BI 工具分析。

4. 环境变量管理进阶：对于拥有大量项目或需要团队协作的场景，可以考虑使用direnv工具。它可以在你进入项目目录时自动加载.env文件，退出时卸载，非常方便。也可以使用 Docker 容器来运行analytics-cli，通过 Docker Secrets 或环境变量文件来管理密钥，实现更好的隔离性和安全性。

5. 监控与告警：你可以扩展自动化脚本，不仅生成报告，还实现简单的监控。例如，检查每日活跃用户是否骤降超过50%，或者关键页面的流量是否消失。一旦检测到异常，脚本可以自动发送告警邮件或 Slack 消息。

#!/bin/bash # 简易流量骤降检查脚本 TODAY=$(date +%Y-%m-%d) YESTERDAY=$(date -v-1d +%Y-%m-%d) cd /path/to/project # 获取今日和昨日的活跃用户数 TODAY_USERS=$(npx analytics-cli ga4 active-users --start $TODAY --end $TODAY --output json | jq '.totalActiveUsers') YESTERDAY_USERS=$(npx analytics-cli ga4 active-users --start $YESTERDAY --end $YESTERDAY --output json | jq '.totalActiveUsers') # 计算跌幅 DROP_RATE=$(echo "scale=2; ($YESTERDAY_USERS - $TODAY_USERS) / $YESTERDAY_USERS * 100" | bc) # 如果跌幅超过阈值，发送告警 if (( $(echo "$DROP_RATE > 50" | bc -l) )); then echo "警告：$TODAY 活跃用户数 ($TODAY_USERS) 较昨日 ($YESTERDAY_USERS) 下跌 $DROP_RATE%" | mail -s "网站流量异常下跌" your-email@example.com fi

通过结合这些进阶技巧，analytics-cli从一个简单的数据查询工具，进化为你网站数据分析自动化工作流的核心枢纽，能持续、稳定、智能地为你的业务决策提供数据支持。