用途 seo-google 通过 Google 官方 API 补充基于爬虫的 SEO 分析,获取 Chrome 真实用户指标、实际收录状态、搜索表现与自然流量数据。
主要能力
- PageSpeed Insights v5:合并 Lighthouse 实验数据与 CrUX 实测数据,默认同时跑移动端与桌面端。
- CrUX:仅查询实测数据(p75 指标);crux-history 提供 25 周 Core Web Vitals 趋势,含各指标趋势方向与变化百分比。
- Search Console:gsc 查询点击、展示、CTR、排名(默认近 28 天,维度为 query、page,并检测排名 4 到 10 的高展示“快速见效”查询);inspect 与 inspect-batch 返回真实收录判定、覆盖率、robots.txt、规范网址、移动可用性、富媒体结果;sitemaps 列出站点地图状态与错误。
- Indexing API v3:提交单个或批量 URL 更新通知,需注意官方仅面向 JobPosting 与 BroadcastEvent/VideoObject 页面,每日 200 次发布配额。
- GA4:自然搜索渠道的会话、用户、页面浏览、跳出率、互动度报告,以及按会话排序的热门自然落地页。
- YouTube:视频搜索与视频详情(含标签与前 10 条评论),用于视频 SEO 参考。
- Google NLP:实体抽取、情感分析与内容分类,用于增强 E-E-A-T 评估;实体单独分析可减少配额消耗。
- 关键词研究:通过 Google Ads Keyword Planner 生成关键词想法与查询搜索量,需 Ads 开发者令牌与客户 ID。
- 补充:Knowledge Graph 实体查询核查品牌存在;Web Risk 检查 URL 的恶意软件与社交工程标记;quotas 显示各 API 速率限制。
使用方式 先运行 python scripts/google_auth.py --check --json 检查凭据,配置文件为 ~/.config/codex-seo/google-api.json,可包含服务账号路径、API Key、默认 Search Console 资源与 GA4 资源 ID。凭据缺失时按 references/auth-setup.md 引导配置 Google Cloud 项目。凭据分四层:Tier 0 仅需 API Key,可用 pagespeed、crux、crux-history、youtube、nlp、entity、safety;Tier 1 增加 OAuth 或服务账号,可用 gsc、inspect、sitemaps、index;Tier 2 配置 GA4 资源后增加 ga4、ga4-pages;Tier 3 配置 Ads 令牌与客户 ID 后增加 keywords、volume。执行命令前应告知用户当前检测到的层级。各命令均有对应 Python 脚本与参考文档,输出支持 JSON,并可在分析后生成 cwv-audit、gsc-performance、indexation、full 四类 PDF 或 HTML 报告。
适用场景 适合需要真实字段数据与收录状态核实的技术 SEO 审计、Core Web Vitals 监控与趋势分析、Search Console 表现与快速见效机会挖掘、自然流量落地页评估、内容实体与情感分析、关键词与搜索量调研,以及视频 SEO 与品牌实体核查。
限制 CrUX 数据不足时返回 404,并非鉴权错误;Search Analytics 数据有 2 到 3 天延迟;URL 检查每站点每日 2,000 次;Indexing API 每日 200 次发布;NLP 免费额度每月 5,000 单位且需启用计费;Custom Search JSON API 自 2025 年起不对新客户开放;INP 已于 2024 年 3 月 12 日取代 FID。API 本身免费,其余收费与平台信息资料未提供。