crawlseo 接入 Google Search Console 完整教程:从零配置 OAuth 到关键词数据同步

原创2026-11-04 10:57:042,344 阅读

crawlseo 接入 Google Search Console 完整教程:从零配置 OAuth 到关键词数据同步

crawlseo 是一款开源、可自托管的 SEO 监控工具。本文带你从零接入 Google Search Console(GSC):在 Google Cloud Console 配置 OAuth 客户端、登录并加密保存令牌、添加站点属性,最后点击 Sync GSC 一键同步关键词排名、点击量与 CTR 数据到本地数据库。

📋 流程一览

步骤 操作 结果
1 启动 crawlseo 项目并填写环境变量 应用跑在 http://localhost:3000
2 创建 Google OAuth 2.0 客户端 拿到 Client ID / Secret
3 Google 账号登录 OAuth 令牌加密入库
4 添加站点并选择 GSC 属性 站点与 Search Console 属性绑定
5 点击 Sync GSC 28 天关键词 + 页面数据入库

🚀 第一步:启动项目并配置环境变量

克隆仓库并初始化数据库(需要 Node.js 20+ 和 Docker):

git clone https://gitcode.com/gh_mirrors/cr/crawlseo
cd crawlseo
cp .env.example .env.local
npm install
docker compose up -d db
npx prisma migrate dev --name init
npm run dev

打开 .env.local,重点填这 4 个变量:

变量 必填 说明
GOOGLE_CLIENT_ID 是 下面第二步创建的 OAuth 客户端 ID
GOOGLE_CLIENT_SECRET 是 OAuth 客户端密钥
NEXTAUTH_SECRET 是 会话密钥,同时用于加密存储的 Google 令牌(openssl rand -hex 32 生成,之后保持稳定)
DATABASE_URL 是 PostgreSQL 连接串,模板里已给默认值

⚠️ NEXTAUTH_SECRET 一旦更换,已加密的 Google 令牌将无法解密,所有用户都需要重新登录。

应用启动后访问 http://localhost:3000,看到登录页即说明环境就绪。

🔑 第二步:创建 Google OAuth 2.0 客户端(GSC API)

  1. 打开 Google Cloud Console,创建或选择一个项目;
  2. 在 APIs & Services → Library 中启用 Google Search Console API;
  3. 进入 Credentials → Create Credentials → OAuth client ID,应用类型选择 Web application;
  4. 在 Authorized redirect URIs 中填写回调地址:
    • 本地开发:http://localhost:3000/api/auth/callback/google
    • 服务器部署:https://你的域名/api/auth/callback/google(并同步设置 NEXTAUTH_URL)
  5. 创建完成后,把 Client ID 和 Client Secret 复制进 .env.local。

crawlseo 只会申请只读的 GSC 权限,相关 scope(openid、email、profile、https://www.googleapis.com/auth/webmasters.readonly)已在 lib/auth.ts 中固定,无需手动改动。

🔐 第三步:Google 登录,OAuth 令牌加密保存

登录页只有一个 Continue with Google 按钮(见 app/(auth)/login/page.tsx/login/page.tsx)):

  1. 点击后跳转到 Google 授权页,选择你的 Google 账号并同意授权;
  2. 授权成功后回到应用,自动跳转 /sites;
  3. 令牌(access token + refresh token)随即被加密写入数据库,明文不会被保留。

这一机制由 lib/google/token-store.ts 实现:令牌带 enc:v1: 前缀加密存储,依赖 NEXTAUTH_SECRET 派生的密钥。令牌过期时,lib/google/google-auth.ts 会用 refresh token 自动续期;只有 refresh token 本身失效时,才需要你重新登录。

🏷️ 第四步:添加站点,绑定 Search Console 属性

进入 Sites 页面,点击 Add site,会弹出 Connect Search Console 对话框:

  1. 应用调用 GET /api/gsc/properties(app/api/gsc/properties/route.ts)拉取你 Google 账号下所有有权限的 GSC 属性;
  2. 在下拉框中选择要接入的属性,例如 sc-domain:example.com 或 example.com/ 前缀格式;
  3. 点击 Connect site,服务端会依据属性自动推导出站点域名并创建站点。

之后在 站点设置 页可以看到该站绑定的 GSC 属性(页面源码见 app/(dashboard)/sites/[siteId]/settings/page.tsx),显示 Not connected 说明还没选属性。

如果下拉框提示 "No GSC properties found",说明当前 Google 账号不是该属性的所有者/管理员,请换账号登录或先在 Search Console 里给自己加权限。

🔄 第五步:一键 Sync GSC,同步 28 天关键词数据

打开站点的 Overview 或 Keywords 页面,点击橙色 Sync GSC 按钮:

crawlseo 接入 Google Search Console 后的总览面板:点击量、展示量、平均排名、CTR 与每日点击趋势

同步过程做了什么(实现见 lib/workers/gsc-sync.ts):

  • 时间窗口:拉取最近 28 天数据,结束日期停在 3 天前——因为 Google 最近 2~3 天的数据本身不完整(数据延迟);
  • 维度:按 query + page + date + device + country 拉取关键词维度,另按 page + date 拉取页面维度(见 lib/google/gsc-client.ts,单次请求 25000 行自动翻页);
  • 入库方式:upsert(按 站点+关键词+日期 去重),重复同步只会更新数值;
  • 异步执行:请求先入任务队列(app/api/gsc/sync/route.ts),按钮依次显示 Queued… → Syncing…,完成后提示 Synced N keywords · N pages。

同步成功后,Overview 出现点击量、展示量、平均排名、CTR 四张指标卡(附 28 天环比涨跌)和每日点击趋势图;Keywords 页面则能按排名、点击、展示量筛选排序,还支持导出 CSV:

crawlseo 关键词页面:Google Search Console 同步后的查询词排名、点击量、展示量与 CTR 数据表

⚙️ 每日自动同步与常见排查

自动同步:默认调度器每天为每个站点执行一次 GSC 同步,同步后自动跑一次告警评估;间隔可用 SCHEDULE_GSC_SYNC_HOURS(默认 24)调整,设为 0 关闭,或整体用 SCHEDULER_ENABLED=false 停用。手动按钮随时可用。

常见问题速查:

现象 原因与处理
Your Google connection has expired. refresh token 已失效,点提示旁的 Reconnect 重新走一次 Google 登录
同步结果 GSC returned no data 属性近期没有搜索数据,去站点设置里核对绑定的 GSC 属性是否正确
添加站点时属性列表为空 当前 Google 账号对该属性无权限,换账号或补权限
登录后所有用户都要重新登录 NEXTAUTH_SECRET 被改过,加密令牌无法解密;保持它稳定即可

✅ 小结

至此你已经完成了 crawlseo 接入 Google Search Console 的全链路:OAuth 客户端配置 → 登录存令牌 → 绑定站点属性 → 手动/自动同步关键词数据。整个过程应用只申请只读权限,所有搜索数据都保存在你自己的数据库里。

想继续深入,可以看看这两个入口:

下一步建议:给站点跑一次 Crawl / Audit 抓取页面级问题,再在 Settings 里配置告警 webhook,让流量骤降时第一时间收到通知。

登录后查看全文
crawlseo