crawlseo 接入 Google Search Console 完整教程:从零配置 OAuth 到关键词数据同步
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)
- 打开 Google Cloud Console,创建或选择一个项目;
- 在 APIs & Services → Library 中启用 Google Search Console API;
- 进入 Credentials → Create Credentials → OAuth client ID,应用类型选择 Web application;
- 在 Authorized redirect URIs 中填写回调地址:
- 本地开发:
http://localhost:3000/api/auth/callback/google - 服务器部署:
https://你的域名/api/auth/callback/google(并同步设置NEXTAUTH_URL)
- 本地开发:
- 创建完成后,把 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)):
- 点击后跳转到 Google 授权页,选择你的 Google 账号并同意授权;
- 授权成功后回到应用,自动跳转
/sites; - 令牌(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 对话框:
- 应用调用
GET /api/gsc/properties(app/api/gsc/properties/route.ts)拉取你 Google 账号下所有有权限的 GSC 属性; - 在下拉框中选择要接入的属性,例如
sc-domain:example.com或example.com/前缀格式; - 点击 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 按钮:
同步过程做了什么(实现见 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:
⚙️ 每日自动同步与常见排查
自动同步:默认调度器每天为每个站点执行一次 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 客户端配置 → 登录存令牌 → 绑定站点属性 → 手动/自动同步关键词数据。整个过程应用只申请只读权限,所有搜索数据都保存在你自己的数据库里。
想继续深入,可以看看这两个入口:
- 完整功能与部署说明:README.md
- 前端同步按钮与结果提示逻辑:components/sites/sync-button.tsx
下一步建议:给站点跑一次 Crawl / Audit 抓取页面级问题,再在 Settings 里配置告警 webhook,让流量骤降时第一时间收到通知。

