WellChina Docs

主题

Google Cloud / GSC / Indexing API 端到端设置指南 ​

版本: v1.0 · 发布: 2026-04-24 适用场景：启用 GSC MCP（GEO Plan Phase 3 硬依赖）+ PageSpeed Insights API + Indexing API + Search Console API 估时：30-60 分钟（含等 GSC 验证生效的 5-15 分钟）

这是从 0 到能在 Claude Code 里直接问 "WellChina 本周哪个页面展现最多？" 的完整 onboarding。每一步都给出精确的菜单路径 + 验证命令。

0. 前置确认 ​

用当前 Google 账号能不能进 GA4 Admin（analytics.google.com → 齿轮 Admin）。不能 → 让 admin 加你成 owner，或让 admin 跑这份指南。

注意：GA4 本身不需要 Google Cloud 项目就能跑。只有配置了 BigQuery Export / server-side GTM 才会自动关联。所以"用 GA4 就一定有 Cloud 项目"不成立 —— 多数情况需要新建一个。

1. 找到（或新建）Cloud 项目 ​

按顺序查三个地方：

1.1 GA4 里确认有无已关联项目（可选） ​

GA4 → Admin → Product Links 分组 → BigQuery Links：

  • 有一行 → 点进去看 Project ID，这就是已有关联的 Cloud 项目，直接用
  • 空 → GA4 没关联任何 Cloud 项目（默认情况）；跳 1.2

1.2 看账号下的所有 Cloud 项目 ​

console.cloud.google.com/projectselector2/home/dashboard 列出该账号有权访问的所有项目。

  • 有 wellchina-* / WellChina / Analytics-xxxxx 之类 → 选它
  • 什么都没有 → 跳 1.3

1.3 新建专用项目（多数情况走这条） ​

Cloud 和 GA4 不必同项目；只要 Google 账号一致，API 授权走账号 OAuth 即可。

  1. console.cloud.google.com → 顶栏项目下拉 → New Project
  2. Name: wellchina-prod
  3. Organization: 个人账号选 "No organization"，有 Workspace 选对应 org
  4. Create

验证：左上角 URL 顶部显示 Project: wellchina-prod（或你选定的那个），而不是 "选择项目"。

2. 启用 3 个 API ​

进 API 库，逐个搜索 + 启用（点 "Enable" 按钮）：

API 名称用途必需性
Google Search Console APIGSC MCP 拉 search analytics 数据🔴 必需
Web Search Indexing API主动通知 Google 抓新页（每天 200 次配额）🟠 推荐
PageSpeed Insights APILighthouse 数据 + Core Web Vitals 自动化🟢 可选

Webmaster Tools API 已被 Google 归并入 Search Console API（2021 年前的旧名），Console 中搜索找不到，忽略即可。

启用后 1-2 分钟内生效。

验证：API & Services → Enabled APIs 应能看到上面的 API 列在列表里。

PageSpeed 额外步骤：若要在 CI 脚本里直接 curl PageSpeed 端点，必须用 API key（Credentials → Create Credentials → API key → 限制到 PageSpeed Insights API）。无 API key 的匿名调用日配额 = 0，会直接 429。

3. 创建凭据 — 选一种 ​

方式 A · OAuth 2.0 Client ID（推荐用于 Claude Code MCP） ​

  1. API & Services → Credentials → Create Credentials → OAuth client ID
  2. 如果是首次创建 OAuth：会先要求配置 OAuth consent screen：
    • User type: External（不选 Internal 除非你有 Workspace org）
    • App name: WellChina GSC MCP
    • User support email: 你的邮箱
    • Developer contact: 同上
    • Scopes: 留空跳过（创建 client 时再加）
    • Test users: 加你自己的 Google 账号邮箱（这一步关键——External app 默认 publishing status 是 Testing，只有 test users 能用）
  3. 回到 Create OAuth client ID：
    • Application type: Desktop app
    • Name: WellChina GSC MCP Desktop
  4. 下载 JSON（按钮 "Download JSON"），重命名为 gcp-oauth-client.json，不要 commit 到 git
  5. 把这个文件路径填到 GSC MCP 配置（具体配置见 GSC MCP 指南）

方式 B · Service Account（推荐用于 server-side cron） ​

  1. Credentials → Create Credentials → Service account
  2. Service account name: wellchina-gsc-reader
  3. Role: 不选（GSC 在 GSC dashboard 里单独授权）
  4. 创建后 → Keys tab → Add Key → JSON → 下载 + 重命名为 gcp-service-account.json，不要 commit
  5. 复制 service account 邮箱（形如 wellchina-gsc-reader@<project>.iam.gserviceaccount.com）
  6. 在 GSC dashboard（search.google.com/search-console）→ Settings → Users and permissions → Add user → 粘贴邮箱 → 权限 Restricted（只读够用）

4. 验证 GSC properties ​

WellChina 应该有 2 种 property（如果只有 1 种，补另 1 种）：

Property 类型值验证方法优势
Domain propertywellchina.topDNS TXT 记录（最严格 = 最可靠）自动覆盖所有子域 + 协议（http/https/www）
URL prefix propertyhttps://www.wellchina.topHTML meta tag / DNS / GA / GTM可独立查特定 URL prefix 数据

添加 Domain property（如缺） ​

  1. GSC dashboard → 顶栏属性下拉 → Add property → Domain
  2. 输入 wellchina.top
  3. Google 会显示一条 TXT 记录（形如 google-site-verification=xxxxxxx）
  4. 在 Cloudflare DNS dashboard（你的 DNS 在 Cloudflare）→ Add record:
    • Type: TXT
    • Name: @（即 wellchina.top 根）
    • Content: google-site-verification=xxxxxxx
    • TTL: Auto
  5. 回 GSC 点 Verify（DNS propagation 一般 1-5 分钟）

添加 URL prefix property（如缺） ​

  1. Add property → URL prefix → 输入 https://www.wellchina.top/
  2. 验证方式选 HTML tag 最简单：
    • 复制 <meta name="google-site-verification" content="xxx" /> 整段
    • 加到 src/app/[locale]/layout.tsx 的 <head>（或 metadata.other 字段）
    • Deploy → 回 GSC 点 Verify

验证：两个 property 都应在 GSC 顶栏下拉里显示绿色勾。

5. 端到端验证：能不能拉数据 ​

5a. 用 curl 测 Search Console API ​

bash
# 用 OAuth flow 拿 access token（推荐用 gcloud CLI）
gcloud auth login
gcloud auth print-access-token

# 用 token 调 Search Console API
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://searchconsole.googleapis.com/webmasters/v3/sites"
# 期望：返回 JSON 含 wellchina.top 和 https://www.wellchina.top/ 两个 site

5b. 用 curl 测 PageSpeed Insights API（需要 API key） ​

bash
# 先在 Console → Credentials → Create Credentials → API key 建一个 key
API_KEY="AIza..."
curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://www.wellchina.top/&strategy=mobile&key=$API_KEY" \
  | jq '.lighthouseResult.categories.performance.score'
# 期望：返回 0-1 的 performance 分数

⚠️ 无 API key 会 429：匿名调用的日配额是 0，不是以前文档里写的"无需鉴权"。

5c. 测 Indexing API ​

bash
# 用 service account（OAuth 也行但需要 google-auth-cli）
ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
curl -X POST "https://indexing.googleapis.com/v3/urlNotifications:publish" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.wellchina.top/hospitals","type":"URL_UPDATED"}'
# 期望：200 + JSON 含 notifyTime

⚠️ Indexing API 配额：每天 200 次 publish + 200 次 inspect。够用，不要循环刷。

6. 接入 Claude Code GSC MCP ​

前提：已完成步骤 1-4（OAuth client JSON 已下载到本地）。 选用：suganthan-gsc-mcp npm 包（20 tools · OAuth · 2026-04 活跃维护 · v2.2.2 修复 OAuth 并发崩溃）。

6a. 放置 OAuth 凭证 ​

bash
mkdir -p ~/.claude/credentials
mv ~/Downloads/client_secret_*.json ~/.claude/credentials/gcp-oauth-client.json
chmod 600 ~/.claude/credentials/gcp-oauth-client.json

文件路径不要放在项目目录（避免误 commit）；~/.claude/credentials/ 在仓库外，天然隔离。

6b. 注册 MCP（一条命令，user scope） ​

bash
claude mcp add gsc --scope user -- npx -y suganthan-gsc-mcp \
  -e GSC_AUTH_MODE=oauth \
  -e GSC_OAUTH_SECRETS_FILE="$HOME/.claude/credentials/gcp-oauth-client.json" \
  -e GSC_SITE_URL="sc-domain:wellchina.top"

关键陷阱：GSC_SITE_URL 必须是 sc-domain:wellchina.top 格式（对应 GSC 的 Domain property），不要用 https://wellchina.top/。用错会 403。

想同时挂 URL prefix property，用 GSC_SITE_URLS 逗号分隔： GSC_SITE_URLS=sc-domain:wellchina.top,https://www.wellchina.top/

6c. 验证注册成功 ​

bash
claude mcp list | grep gsc            # 应看到 gsc: npx ... ✓ Connected

6d. 首次 OAuth 授权 ​

在 Claude Code 里问：

> 列出我 GSC 的所有 site

第一次调用会自动弹浏览器 → 选加到 OAuth consent screen Test users 里的那个 Google 账号 → Allow → token 自动缓存到 ~/.config/suganthan-gsc-mcp/token.json（或平台对应路径），之后不再需要。

6e. 烟雾测试 ​

> wellchina.top 过去 7 天 top 10 query 是什么
> /seo google quick_wins wellchina.top     # 如装了 claude-seo:seo-google plugin

期望：返回真实 GSC 数据（有 2-3 天延迟是正常的，见 GSC 指南 §8.2）。

6f. 故障时的卸载/重装 ​

bash
claude mcp remove gsc --scope user
rm -f ~/.config/suganthan-gsc-mcp/token.json   # 清 token 重新授权
# 然后重跑 6b

7. 常见故障排查 ​

现象原因解决
OAuth consent screen 报 "App not verified"External app 仍在 Testing 状态加你自己邮箱到 Test users（步骤 3a）；不需要正式 publish
403 Forbidden 调 Search Console APIproperty 没授权给 service account在 GSC → Users 加 service account 邮箱
429 Quota exceededIndexing API 当天 200 配额耗尽等 24h 重置；考虑批 sitemap 提交替代
Domain property TXT 验证失败Cloudflare proxy 影响 DNS 解析TXT 记录不走 proxy（Cloudflare TXT 默认就是 DNS-only），等 5 min 重试
GSC 拉到的数据为空property 才刚验证GSC 数据有 2-3 天延迟，新 property 至少等 48h

8. 安全 checklist ​

  • [ ] OAuth client JSON / service account JSON 不在 git（加到 .gitignore）
  • [ ] Service account 权限选 Restricted（只读）而不是 Full
  • [ ] Service account key 90 天轮换一次（Console → IAM → Service accounts → Keys）
  • [ ] OAuth consent screen 的 Test users 列表只含真实需要的人
  • [ ] Indexing API 用专用 service account，不复用其他用途的 key

相关文档 ​

WellChina 内部文档 · 基于 VitePress

© 2026 WellChina