google-search-console-cli

Google Search Console CLI 技能

你可以使用 google-search-console-cli，这是一个用于 Google Search Console API 的命令行工具。使用它查询搜索分析数据、检查 URL 索引状态，以及管理网站和站点地图。

快速开始

# Check if the CLI is available
google-search-console-cli --help

# List accessible sites
google-search-console-cli sites

如果尚未安装 CLI，请安装：

npm install -g google-search-console-cli

身份验证

CLI 使用 Google 服务账号。凭据按以下顺序解析：

1. --credentials <path> 标志（单条命令）
2. GOOGLE_APPLICATION_CREDENTIALS 环境变量
3. ~/.config/google-search-console-cli/credentials.json（自动检测）
4. gcloud 应用默认凭据

运行任何命令前，请运行 google-search-console-cli sites，确认凭据已配置。如果因凭据错误而失败，请让用户设置身份验证。

网站 URL 格式

Search Console 使用两种资源类型：

• URL 前缀资源：https://www.example.com/（必须包含末尾斜杠和协议）
• 网域资源：sc-domain:example.com（涵盖所有协议和子网域）

始终使用在 Search Console 中注册的准确格式。对于大多数命令，网站 URL 是位置参数。

输出格式

默认情况下，所有命令都会输出美化格式的 JSON。使用 --format compact 可输出单行 JSON（便于通过管道传递）。

命令

搜索分析查询

query 命令是查询搜索效果数据的主要工具。

google-search-console-cli query <siteUrl> --start-date <date> --end-date <date> [options]

必需参数：

• --start-date <date> -- 开始日期（YYYY-MM-DD）
• --end-date <date> -- 结束日期（YYYY-MM-DD）

可选参数：

• --dimensions <names> -- 以逗号分隔：date、query、page、country、device、searchAppearance、hour
• --type <type> -- 搜索类型：web（默认）、image、video、news、discover、googleNews
• --dimension-filter <json> -- 维度筛选条件组的 JSON 数组（见下文）
• --aggregation-type <type> -- auto、byPage、byProperty、byNewsShowcasePanel
• --row-limit <n> -- 最大行数，1-25000（默认 1000）
• --start-row <n> -- 起始行偏移量（默认 0）
• --data-state <state> -- 数据新鲜度：all、final、hourly_all
• --all -- 使用自动分页获取所有行（不能与 --start-row 同时使用）

每行响应字段：

• keys -- 维度值数组（顺序与 --dimensions 指定的顺序相同）
• clicks -- 点击次数
• impressions -- 展示次数
• ctr -- 点击率（0.0 到 1.0）
• position -- 搜索结果中的平均排名

使用 --all 自动分页

指定 --all 时，CLI 会自动分页获取所有结果（每页 25000 行），并返回完整数据集。这适用于导出所有数据，无需手动分页。

# Get ALL queries (auto-paginates through all pages)
google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --all

注意：--all 和 --start-row 不能同时使用。使用 --all 时，--row-limit 会被忽略。

网站管理

# List all sites
google-search-console-cli sites

# Get info about a specific site
google-search-console-cli site <siteUrl>

# Add a site (requires Full permission)
google-search-console-cli site-add <siteUrl>

# Remove a site (requires Full permission)
google-search-console-cli site-remove <siteUrl>

站点地图管理

# List sitemaps for a site
google-search-console-cli sitemaps <siteUrl>

# List sitemaps under a specific sitemap index
google-search-console-cli sitemaps <siteUrl> --sitemap-index <url>

# Get info about a specific sitemap
google-search-console-cli sitemap <siteUrl> <feedpath>

# Submit a sitemap (requires Full permission)
google-search-console-cli sitemap-submit <siteUrl> <feedpath>

# Delete a sitemap (requires Full permission)
google-search-console-cli sitemap-delete <siteUrl> <feedpath>

URL 检查

# Inspect a single URL's index status
google-search-console-cli inspect <siteUrl> <inspectionUrl>

# With a specific language for messages
google-search-console-cli inspect <siteUrl> <inspectionUrl> --language zh-CN

--language 选项用于控制响应消息的语言（默认：en-US）。

响应内容包括：索引状态（索引情况、抓取时间、robots.txt 状态、规范 URL）、AMP 分析（如适用）、移动设备易用性，以及富媒体搜索结果检测。

批量检查 URL

在单条命令中检查多个 URL：

# From a file (one URL per line)
google-search-console-cli inspect-batch https://www.example.com/ --file urls.txt

# From stdin
cat urls.txt | google-search-console-cli inspect-batch https://www.example.com/

# With compact format (NDJSON, streams results as they complete)
cat urls.txt | google-search-console-cli inspect-batch https://www.example.com/ --format compact

选项：

• --file <path> -- 包含 URL 的文件（每行一个）；省略时从 stdin 读取
• --language <code> -- 消息使用的语言代码（默认：en-US）

进度会写入 stderr：Inspecting 1/50: https://...

使用 --format compact 时，每个结果会在完成后立即以 NDJSON 格式（每行一个 JSON 对象）流式输出。使用 --format json（默认）时，会收集所有结果，并在最后以 JSON 数组形式输出。

每个 URL 的错误都会记录在输出中（包含 error 字段，以及在可用时包含 code 字段，例如 403 或 429），且不会中断批量处理。如果任何 URL 失败，命令仍会打印所有结果，然后将 {"error": "N of M URLs failed inspection."} 写入 stderr，并以代码 1 退出。请检查各 URL 的 error 字段，查看哪些 URL 失败。

维度过滤器组

--dimension-filter 选项接受一个由过滤器组组成的 JSON 数组。每个过滤器组包含：

• groupType -- "and"（必须匹配所有过滤器）
• filters -- 过滤器对象数组

每个过滤器对象：

• dimension -- 可选值：query、page、country、device、searchAppearance
• operator -- 可选值：equals、notEquals、contains、notContains、includingRegex、excludingRegex
• expression -- 要匹配的值

国家/地区代码使用 3 个字母的 ISO 3166-1 alpha-3 格式（例如：USA、GBR、DEU、JPN）。

设备值：DESKTOP、MOBILE、TABLET。

过滤器示例

单个过滤器：

[{"groupType":"and","filters":[{"dimension":"country","operator":"equals","expression":"USA"}]}]

多个过滤器（AND）：

[{"groupType":"and","filters":[{"dimension":"country","operator":"equals","expression":"USA"},{"dimension":"device","operator":"equals","expression":"MOBILE"}]}]

正则表达式过滤器：

[{"groupType":"and","filters":[{"dimension":"query","operator":"includingRegex","expression":"buy|purchase|order"}]}]

页面过滤器：

[{"groupType":"and","filters":[{"dimension":"page","operator":"contains","expression":"/blog/"}]}]

实用示例

热门搜索查询

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --row-limit 50

每日效果趋势

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions date

按点击次数排列的热门页面

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions page \
  --row-limit 50

按国家/地区划分的效果

google-search-console-cli query sc-domain:example.com \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions country

按设备划分的效果

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions device

特定页面的查询效果

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --dimension-filter '[{"groupType":"and","filters":[{"dimension":"page","operator":"equals","expression":"https://www.example.com/product"}]}]'

特定国家/地区的移动设备效果

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --dimension-filter '[{"groupType":"and","filters":[{"dimension":"country","operator":"equals","expression":"USA"},{"dimension":"device","operator":"equals","expression":"MOBILE"}]}]'

品牌与非品牌查询

# Brand queries
google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --dimension-filter '[{"groupType":"and","filters":[{"dimension":"query","operator":"includingRegex","expression":"example|exmpl"}]}]'

# Non-brand queries
google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --dimension-filter '[{"groupType":"and","filters":[{"dimension":"query","operator":"excludingRegex","expression":"example|exmpl"}]}]'

博客版块效果

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions page \
  --dimension-filter '[{"groupType":"and","filters":[{"dimension":"page","operator":"contains","expression":"/blog/"}]}]'

图片搜索效果

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --type image \
  --row-limit 50

哪些页面在特定查询中获得排名（关键词蚕食检查）

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions page \
  --dimension-filter '[{"groupType":"and","filters":[{"dimension":"query","operator":"equals","expression":"best running shoes"}]}]'

跨维度分析（查询 x 页面）

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query,page \
  --row-limit 100

随时间变化的设备趋势

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions date,device

Google 新闻效果

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions page \
  --type googleNews

Discover 信息流效果

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions page \
  --type discover

每小时效果趋势（含最新数据）

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-03-17 \
  --end-date 2026-03-17 \
  --dimensions hour \
  --data-state hourly_all

按页面汇总（按页面去重）

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions page \
  --aggregation-type byPage

获取所有行（自动分页）

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --all

对大型结果集分页（手动）

# First 1000 rows
google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --row-limit 1000

# Next 1000 rows
google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --row-limit 1000 \
  --start-row 1000

搜索外观细分

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions searchAppearance

检查 URL 的索引状态

google-search-console-cli inspect https://www.example.com/ https://www.example.com/important-page

批量检查多个 URL

# Create a file with URLs to inspect
echo "https://www.example.com/page1
https://www.example.com/page2
https://www.example.com/page3" > urls.txt

# Batch inspect
google-search-console-cli inspect-batch https://www.example.com/ --file urls.txt

# Or pipe from another command
google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 --end-date 2026-03-17 \
  --dimensions page --format compact \
  | jq -r '.rows[].keys[0]' \
  | google-search-console-cli inspect-batch https://www.example.com/ --format compact

审核站点地图

# List all sitemaps
google-search-console-cli sitemaps https://www.example.com/

# Check a specific sitemap
google-search-console-cli sitemap https://www.example.com/ https://www.example.com/sitemap.xml

工作流指南

用户要求概览搜索效果时

1. 运行 google-search-console-cli sites，查找可访问的网站
2. 使用 --dimensions date 运行 query，查看每日趋势
3. 使用 --dimensions query 运行 query，查看热门查询
4. 展示关键指标：总点击次数、展示次数、平均 CTR、平均排名

用户询问特定页面的 SEO 时

1. 使用 --dimensions query 和针对页面 URL 的 --dimension-filter 运行 query
2. 使用 inspect 检查页面的索引状态
3. 交叉参考查询排名（位置）与索引健康状况

用户询问移动设备与桌面设备的效果对比时

1. 使用 --dimensions device 运行 query，查看概览
2. 可选：使用 --dimensions query,device 深入分析，找出在不同设备上效果有差异的查询

用户询问国际效果时

1. 使用 --dimensions country 运行 query，查看各国家/地区的细分数据
2. 使用 --dimension-filter 深入查看特定国家/地区

当用户询问索引问题时

1. 对于特定 URL，使用 inspect；对于批量检查，使用 inspect-batch
2. 使用 sitemaps 和 sitemap 命令检查站点地图
3. 查看检查响应，确认是否存在抓取错误、索引屏蔽或移动设备易用性问题

当用户想要导出所有搜索数据时

1. 使用 query 和 --all 自动翻页获取所有结果
2. 使用 --format compact 输出适合通过管道传递给 jq 或其他工具的 NDJSON

权限级别

• 只读（受限）：sites、site、query、sitemaps、sitemap、inspect、inspect-batch
• 写入（完整）：site-add、site-remove、sitemap-submit、sitemap-delete

大多数分析工作流只需要只读权限。

错误处理

• 身份验证错误 —— 请用户确认其服务账号凭据
• 403 权限被拒绝 —— 服务账号无权访问该网站；必须在 Search Console 设置中为每个网站添加该账号
• 结果为空 —— 检查日期范围（数据通常会在日期过后 2–3 天可用），并确认网站 URL 格式与已注册的资源一致
• 400 错误请求 —— 检查维度筛选器 JSON 语法以及字段兼容性

API 文档参考

参考资料	使用场景
google-search-console-cli 文档	完整 README、设置指南、安装
Search Analytics API	查询方法、维度、筛选器、响应格式
URL Inspection API	检查方法、请求/响应字段
Sites API	网站管理方法和权限级别
Sitemaps API	站点地图管理方法和资源字段