1. 项目概述与核心价值如果你和我一样日常工作中需要频繁查看 Google Analytics 4 (GA4) 和 Google Search Console (GSC) 的数据但又厌倦了在浏览器里反复点击、筛选、导出的繁琐流程那么analytics-cli这个工具的出现绝对能让你眼前一亮。它本质上是一个命令行工具让你能像在终端里执行ls或grep一样直接获取网站的分析数据。这个项目最初的设计动机是为了替代 Cursor 编辑器中的 MCPModel Context Protocol服务器提供一个更轻量、更直接、不依赖特定 IDE 的数据获取方案。简单来说它解决了几个核心痛点自动化、脚本化和集成化。想象一下你不再需要每天手动登录后台截图而是写一个简单的 Shell 脚本定时运行analytics-cli命令就能把昨天的关键指标自动发到你的团队 Slack 频道或生成日报。或者当你正在用 Cursor 进行 AI 编程时可以直接在聊天框里问“上个月流量最高的页面是哪些”AI 会通过集成的 Skill 自动调用这个 CLI 来获取答案实现真正的“对话式数据分析”。这个工具的核心用户是那些需要将数据分析流程嵌入到自动化脚本、CI/CD 流水线或者希望与 AI 助手深度集成的开发者、运维和增长工程师。它不追求替代 GA4 或 GSC 的完整后台而是专注于成为一个高效、可靠的数据“管道”让你能用程序员最熟悉的方式——命令行来操控你的业务数据。2. 核心设计思路与架构解析2.1 为什么选择 CLI 而非 GUI 或 SDKanalytics-cli选择命令行接口作为主要形态背后有非常务实的考量。首先可编程性是 CLI 的天然优势。任何命令行输出都可以通过管道 (|) 传递给grep,awk,jq等工具进行二次处理或者直接写入文件、发送 HTTP 请求无缝融入现有的自动化生态。其次资源消耗极低。它不需要运行一个常驻的图形界面或 Web 服务器仅在执行命令时调用 Google API获取数据后立即退出对系统资源非常友好。最后环境一致性。无论是在本地开发机、远程服务器还是 Docker 容器中CLI 的运行方式都是一致的避免了 GUI 工具因操作系统或桌面环境不同带来的兼容性问题。项目的架构非常清晰遵循了 Unix 哲学中的“只做一件事并做好”的原则。它本质上是一个 Node.js 脚本的封装核心依赖是 Google 官方提供的googleapisnpm 库。整个工具没有复杂的中间层你的命令参数经过解析后直接转换为对应 Google APIAnalytics 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 创建服务账号访问 Google Cloud Console 。选择或创建一个项目这个项目只是一个用于管理 API 和凭证的容器不一定是你网站所在的 GCP 项目。导航到IAM 和管理 服务账号。点击“创建服务账号”输入一个易于识别的名称如analytics-cli-sa然后点击“创建并继续”。在“授予此服务账号对项目的访问权限”步骤暂时不需要添加任何角色直接点击“继续”然后“完成”。角色我们将在下一步针对具体 API 授予。第二步创建并下载 JSON 密钥在刚创建的服务账号列表中找到该账号点击其右侧的“操作”菜单三个点选择“管理密钥”。点击“添加密钥” “创建新密钥”。密钥类型选择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-sayour-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 访问权限在 Google Cloud Console 中为你当前的项目启用Google Analytics Data API。登录到你的 Google Analytics 4 后台。进入“管理”左下角齿轮图标 “媒体资源”列下的“媒体资源访问权限管理”。点击“” “添加用户”。在“电子邮件地址”栏中填入你 JSON 文件中的client_email即服务账号邮箱。角色选择查看者。对于 CLI 工具只读获取数据来说这个权限足够了。点击“添加”。现在这个服务账号就有权读取该 GA4 媒体资源的数据了。你需要知道该媒体资源的数字 ID即GA_VIEW_ID。你可以在“管理” “媒体资源设置”中找到“媒体资源 ID”它是一串数字。第五步配置 Search Console 访问权限在 Google Cloud Console 中同样为你的项目启用Google Search Console API。登录到你的 Google Search Console 。选择你要管理的网站属性。点击左侧“设置” “用户和权限”。点击“添加用户”。同样填入服务账号的client_email。权限选择“受限”实际上对于 API 访问“完全”权限通常不是必须的“受限”即可提供数据读取权限但为确保无误可以先尝试“完全”如果 API 调用失败再调整。点击“添加”。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_EMAILanalytics-cli-sayour-project-123456.iam.gserviceaccount.com GA_PRIVATE_KEY-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCq...此处是长长的密钥...\n-----END PRIVATE KEY-----\n GA_VIEW_ID3456789012安全警告.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 --date30 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 215. 进阶技巧、疑难排查与性能优化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 常见错误与解决方案速查表在实际使用中你可能会遇到以下问题。这里是一个快速排查指南错误信息或现象可能原因解决方案Error: invalid_grant/Invalid JWT signature1..env.local中GA_PRIVATE_KEY的格式错误换行符\n丢失或未正确转义。2. 系统时间不同步。1. 确保私钥字符串被双引号包围且内部的\n原样保留。最可靠的方法是从 JSON 文件直接复制整段private_key值。2. 使用date命令检查服务器时间并使用ntpdate或systemctl restart systemd-timesyncd同步时间。User does not have sufficient permissions...服务账号没有被正确添加到 GA4 或 GSC 的权限列表中。1. 确认GA_CLIENT_EMAIL填写无误。2. 登录 GA4/GSC 后台在“用户管理”中确认该邮箱已存在且角色至少为“查看者”。3.注意延迟权限更改可能需要几分钟才能生效。The caller does not have permissionGoogle Cloud 项目中未启用相应的 API。前往 Google Cloud Console 在对应项目中搜索并启用Google Analytics Data API和/或Google Search Console API。Site [xxx] not found in Search Console.--site参数格式错误或服务账号无权访问该属性。1. 确认--site的格式sc-domain:或完整 URL。2. 登录 Search Console确认服务账号邮箱已被添加到该特定属性而非父级属性的用户列表中。命令执行后无输出或卡住Node.js 环境问题或网络连接问题。1. 运行node --version确认版本 18。2. 尝试运行npx analytics-cli --help看是否有输出排除基础命令问题。3. 检查网络连接特别是能否访问*.googleapis.com。返回数据为空但无错误查询日期范围内确实没有数据或维度/指标组合无效。1. 在 GA4/GSC 网页后台确认对应日期有数据。2. 尝试一个更宽泛的查询如只指定--dimensions date看是否有基础数据返回。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 scale2; ($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-emailexample.com fi通过结合这些进阶技巧analytics-cli从一个简单的数据查询工具进化为你网站数据分析自动化工作流的核心枢纽能持续、稳定、智能地为你的业务决策提供数据支持。
命令行工具 analytics-cli：自动化获取GA4与GSC数据，集成AI与CI/CD
1. 项目概述与核心价值如果你和我一样日常工作中需要频繁查看 Google Analytics 4 (GA4) 和 Google Search Console (GSC) 的数据但又厌倦了在浏览器里反复点击、筛选、导出的繁琐流程那么analytics-cli这个工具的出现绝对能让你眼前一亮。它本质上是一个命令行工具让你能像在终端里执行ls或grep一样直接获取网站的分析数据。这个项目最初的设计动机是为了替代 Cursor 编辑器中的 MCPModel Context Protocol服务器提供一个更轻量、更直接、不依赖特定 IDE 的数据获取方案。简单来说它解决了几个核心痛点自动化、脚本化和集成化。想象一下你不再需要每天手动登录后台截图而是写一个简单的 Shell 脚本定时运行analytics-cli命令就能把昨天的关键指标自动发到你的团队 Slack 频道或生成日报。或者当你正在用 Cursor 进行 AI 编程时可以直接在聊天框里问“上个月流量最高的页面是哪些”AI 会通过集成的 Skill 自动调用这个 CLI 来获取答案实现真正的“对话式数据分析”。这个工具的核心用户是那些需要将数据分析流程嵌入到自动化脚本、CI/CD 流水线或者希望与 AI 助手深度集成的开发者、运维和增长工程师。它不追求替代 GA4 或 GSC 的完整后台而是专注于成为一个高效、可靠的数据“管道”让你能用程序员最熟悉的方式——命令行来操控你的业务数据。2. 核心设计思路与架构解析2.1 为什么选择 CLI 而非 GUI 或 SDKanalytics-cli选择命令行接口作为主要形态背后有非常务实的考量。首先可编程性是 CLI 的天然优势。任何命令行输出都可以通过管道 (|) 传递给grep,awk,jq等工具进行二次处理或者直接写入文件、发送 HTTP 请求无缝融入现有的自动化生态。其次资源消耗极低。它不需要运行一个常驻的图形界面或 Web 服务器仅在执行命令时调用 Google API获取数据后立即退出对系统资源非常友好。最后环境一致性。无论是在本地开发机、远程服务器还是 Docker 容器中CLI 的运行方式都是一致的避免了 GUI 工具因操作系统或桌面环境不同带来的兼容性问题。项目的架构非常清晰遵循了 Unix 哲学中的“只做一件事并做好”的原则。它本质上是一个 Node.js 脚本的封装核心依赖是 Google 官方提供的googleapisnpm 库。整个工具没有复杂的中间层你的命令参数经过解析后直接转换为对应 Google APIAnalytics 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 创建服务账号访问 Google Cloud Console 。选择或创建一个项目这个项目只是一个用于管理 API 和凭证的容器不一定是你网站所在的 GCP 项目。导航到IAM 和管理 服务账号。点击“创建服务账号”输入一个易于识别的名称如analytics-cli-sa然后点击“创建并继续”。在“授予此服务账号对项目的访问权限”步骤暂时不需要添加任何角色直接点击“继续”然后“完成”。角色我们将在下一步针对具体 API 授予。第二步创建并下载 JSON 密钥在刚创建的服务账号列表中找到该账号点击其右侧的“操作”菜单三个点选择“管理密钥”。点击“添加密钥” “创建新密钥”。密钥类型选择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-sayour-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 访问权限在 Google Cloud Console 中为你当前的项目启用Google Analytics Data API。登录到你的 Google Analytics 4 后台。进入“管理”左下角齿轮图标 “媒体资源”列下的“媒体资源访问权限管理”。点击“” “添加用户”。在“电子邮件地址”栏中填入你 JSON 文件中的client_email即服务账号邮箱。角色选择查看者。对于 CLI 工具只读获取数据来说这个权限足够了。点击“添加”。现在这个服务账号就有权读取该 GA4 媒体资源的数据了。你需要知道该媒体资源的数字 ID即GA_VIEW_ID。你可以在“管理” “媒体资源设置”中找到“媒体资源 ID”它是一串数字。第五步配置 Search Console 访问权限在 Google Cloud Console 中同样为你的项目启用Google Search Console API。登录到你的 Google Search Console 。选择你要管理的网站属性。点击左侧“设置” “用户和权限”。点击“添加用户”。同样填入服务账号的client_email。权限选择“受限”实际上对于 API 访问“完全”权限通常不是必须的“受限”即可提供数据读取权限但为确保无误可以先尝试“完全”如果 API 调用失败再调整。点击“添加”。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_EMAILanalytics-cli-sayour-project-123456.iam.gserviceaccount.com GA_PRIVATE_KEY-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCq...此处是长长的密钥...\n-----END PRIVATE KEY-----\n GA_VIEW_ID3456789012安全警告.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 --date30 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 215. 进阶技巧、疑难排查与性能优化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 常见错误与解决方案速查表在实际使用中你可能会遇到以下问题。这里是一个快速排查指南错误信息或现象可能原因解决方案Error: invalid_grant/Invalid JWT signature1..env.local中GA_PRIVATE_KEY的格式错误换行符\n丢失或未正确转义。2. 系统时间不同步。1. 确保私钥字符串被双引号包围且内部的\n原样保留。最可靠的方法是从 JSON 文件直接复制整段private_key值。2. 使用date命令检查服务器时间并使用ntpdate或systemctl restart systemd-timesyncd同步时间。User does not have sufficient permissions...服务账号没有被正确添加到 GA4 或 GSC 的权限列表中。1. 确认GA_CLIENT_EMAIL填写无误。2. 登录 GA4/GSC 后台在“用户管理”中确认该邮箱已存在且角色至少为“查看者”。3.注意延迟权限更改可能需要几分钟才能生效。The caller does not have permissionGoogle Cloud 项目中未启用相应的 API。前往 Google Cloud Console 在对应项目中搜索并启用Google Analytics Data API和/或Google Search Console API。Site [xxx] not found in Search Console.--site参数格式错误或服务账号无权访问该属性。1. 确认--site的格式sc-domain:或完整 URL。2. 登录 Search Console确认服务账号邮箱已被添加到该特定属性而非父级属性的用户列表中。命令执行后无输出或卡住Node.js 环境问题或网络连接问题。1. 运行node --version确认版本 18。2. 尝试运行npx analytics-cli --help看是否有输出排除基础命令问题。3. 检查网络连接特别是能否访问*.googleapis.com。返回数据为空但无错误查询日期范围内确实没有数据或维度/指标组合无效。1. 在 GA4/GSC 网页后台确认对应日期有数据。2. 尝试一个更宽泛的查询如只指定--dimensions date看是否有基础数据返回。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 scale2; ($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-emailexample.com fi通过结合这些进阶技巧analytics-cli从一个简单的数据查询工具进化为你网站数据分析自动化工作流的核心枢纽能持续、稳定、智能地为你的业务决策提供数据支持。
