给博客接入 Google 登录时,本地跑通 localhost:3000 很容易,线上开放给外部读者则取决于一套跨平台的信任契约:浏览器只负责发起跳转和接收站点 Cookie;Google 校验授权网域与回调地址后,把授权码交给 Cloudflare Worker;Worker 用 Better Auth 换取令牌并在 D1 建立会话。
下面以 blog.example.com(根域 example.com)为例,记录生产环境从域名绑定到外部发布的完整配置。
1. 绑定自定义生产域名
OAuth 回调、Cookie 作用域和 Google 品牌验证都需要稳定的生产 HTTPS 来源,不能使用临时的 *.workers.dev。
在 Cloudflare 将 blog.example.com 绑定到生产 Worker(与 wrangler.jsonc 保持一致)。站点以此地址生成 canonical、RSS 与 Sitemap,旧的 workers.dev 链接通过 308 跳转并保留原路径。

2. 验证根域所有权
Google 要求外部 OAuth 应用证明「已获授权的网域」归属。此处必须使用对生产 Google Cloud 项目拥有所有者或编辑者权限的同一个 Google 账号操作,否则 Google Auth Platform 无法关联验证结果。
在 Google Search Console 添加 example.com 网域资源,将生成的 google-site-verification=... 作为 @ 的 TXT 记录写入 Cloudflare DNS。验证通过后保留该 TXT 记录,供 Google 定期复核。

3. 配置 Google Auth Platform
在 Google Cloud Console 打开「Google Auth Platform」,依次完成品牌、范围与 Web 客户端配置。
品牌塑造与授权网域
应用首页、隐私政策(/privacy)与服务条款(/terms)必须公开可访问,且归属在已验证的根域 example.com 下。

数据访问范围
仅勾选 openid、userinfo.email、userinfo.profile 三个非敏感范围。不申请敏感或受限范围,可直接走基础品牌验证,无需额外安全审计。

Web 客户端与本地隔离
创建 Web 应用客户端时:
- 已获授权的 JavaScript 来源:留空,授权码由 Worker 在服务端换取。
- 已获授权的重定向 URI:精确填写
https://blog.example.com/api/auth/callback/google。

客户端创建后立即保存一次性显示的密钥,仓库只保留字段名。本地开发单独使用一个测试项目和 Web 客户端,回调仅配 http://localhost:3000/api/auth/callback/google,写入本地 .dev.vars,不与生产客户端混用。
Google OAuth 客户端管理 · Google OAuth 生产政策 · Better Auth Google 提供方
4. 运行时密钥与自动发布
OAuth 凭据属于运行时配置,存放在生产 Worker 的「运行时变量和密钥」中(BETTER_AUTH_URL 设为 https://blog.example.com);Workers Builds 的构建环境只放构建与发布所需的 Cloudflare 凭据,两者分开管理。

核对 Workers Builds 生产配置后,推送 main 触发自动部署(依次执行 pnpm verify && pnpm build 与 pnpm release):
| 配置项 | 值 |
|---|---|
| GitHub 仓库 | your-account/personal-blog |
| 生产分支 | main |
| 构建命令 | pnpm verify && pnpm build |
| 部署命令 | pnpm release |
Cloudflare Workers 运行时密钥 · Cloudflare Workers Builds 配置
5. 发布正式版与验收
外部应用默认处于「测试版」,仅测试名单内的账号可登录。上线按先内测、后发布的顺序验收:
- 测试态闭环:用测试名单内的账号从文章页发起 Google 登录,验证授权后跳回原文,以及收藏、取消收藏和退出;再用 GitHub 登录交叉验证。
- 切为正式版:在「目标对象」将应用发布为「正式版」,并在「验证中心」提交品牌验证。
- 外部账号终验:换一个未加入测试名单的外部 Google 账号走完登录与收藏,确认退出后收藏写接口拒绝未登录请求。


常见错误速查
| 现象 | 核对项 |
|---|---|
Google 显示 redirect_uri_mismatch | 核对生产客户端 ID,将重定向 URI 与 /api/auth/callback/google 逐字比对 |
| Worker 回调后退回登录页 | 核对 Worker Secret 的 ID 与密钥来自同一客户端;查看 Worker 日志,从正式域名重新发起登录以刷新 OAuth state |
| 外部用户无法授权 | 在「目标对象」核对是否已切为正式版,在「验证中心」检查品牌或授权域状态 |
| 域名访问返回证书错误 | 核对 Cloudflare 区域激活状态、Worker 自定义域名绑定与证书签发状态 |
| 更换 Google 客户端密钥 | 先在 Google 客户端新增密钥,更新生产 Worker Secret 并登录验收通过后,再撤销旧密钥 |
