Saavo

配置 Google OAuth

配置 Google Auth Platform，创建 Web 应用客户端，并接通 Saavo 的 Google 登录和 One Tap。

Saavo 支持普通的 Google OAuth 登录，也支持可选的 Google One Tap。两种方式可以使用同一个 Web application Client ID，但配置要求不同：

  • 普通 Google 登录依赖完整的 Authorized redirect URI；
  • Google One Tap 还要求当前站点出现在 Authorized JavaScript origins 中，并在 Saavo 配置里显式开启。

模板的普通登录流程只申请 openid、email 和 profile，用于确认用户身份、邮箱、姓名和头像，不会申请 Gmail、Drive 等权限。

先整理要填写的地址

Google 登录的默认回调路径在 config/deploy.ts 中：

config/deploy.ts
ui: {
    oauthRedirectTo: {
        github: '/api/auth/oauth2/github',
        google: '/api/auth/oauth2/google',
    },
},

以 WebpageToPDF 为例，需要准备：

环境Authorized JavaScript originAuthorized redirect URI
本地http://127.0.0.1:5173http://127.0.0.1:5173/api/auth/oauth2/google
首次部署https://<实际的 workers.dev 域名>https://<实际的 workers.dev 域名>/api/auth/oauth2/google
正式域名https://webpagetopdf.devhttps://webpagetopdf.dev/api/auth/oauth2/google

JavaScript origin 只能包含协议、主机名和端口，不能带路径。Redirect URI 必须包含完整回调路径。两者不能互换。

先运行 npm run dev，使用终端实际显示的本地地址。如果 Vite 换了端口，Google Cloud 中的本地 Origin 和 Redirect URI 都要一起更新。生产环境则以 .env.production 中的 VITE_SITE_URL 为准。

创建 Google Cloud 项目

进入 Google Auth Platform

登录 Google Cloud Console，在顶部选择已有项目，或者新建一个专门用于 WebpageToPDF 登录的项目。然后打开 Google Auth Platform。

Select or Create a Project

不要随便复用不清楚用途的旧项目。OAuth 品牌、用户范围和客户端凭据都属于当前 Google Cloud 项目，选错项目后创建的 Client ID 也会跟着留在错误的项目中。

在 Google Cloud 侧边栏，点击 Oauth consent screen 菜单。

open Oauth consent screen

进入 Google Auth Platform 的配置页面。

Google Auth Platform configuration

点击右侧中间的 Get Started 按钮，进入配置详情：

Google Auth Platform Project configuration

填写应用名称、选择邮箱等信息后，进入下一步。

Google Auth Platform Audience

选择 External 选项，点击下一步。

Google Auth Platform Contact Information

填写联系人信息后，进入下一步，勾选协议，点击 Create 按钮创建。

设置 Branding

创建完成后，会自动跳转到 Branding 页面，在这个页面中可以补全 App 的相关信息。

Google Auth Platform Branding

其中 Authorized domains 是必填项，其它的选项我也推荐填写，以增加审核通过的概率。

填写完点击 Save 按钮保存。

Google 对 Branding、Audience 和 Data Access 的界面会持续调整，最新入口和字段含义以 Google Identity Services 设置说明为准。

创建 OAuth 客户端

新建 Web application 客户端

在 Google Auth Platform 中打开 Clients 页面：

Open Clients page

点击 Create client，Application type 选择 Web application。名称可以填写 Webpage to PDF。

Create Web application client

不要选择 Desktop app、Chrome extension 或其他类型。Saavo 的回调由网站服务端接收，需要 Web application 客户端。

添加 JavaScript origins

在 Authorized JavaScript origins 中添加实际会显示 Google One Tap 的站点 Origin，例如：

http://127.0.0.1:5173
https://webpagetopdf.dev

Origin 不包含结尾路径，也不使用通配符。

Add JavaScript origins

如果你暂时不开启 One Tap，普通 OAuth 登录不依赖这里的配置，但建议在创建客户端时一并填好，后面启用 One Tap 时可以直接使用。

添加 redirect URIs

在 Authorized redirect URIs 中添加完整回调地址，例如：

http://127.0.0.1:5173/api/auth/oauth2/google
https://webpagetopdf.dev/api/auth/oauth2/google

如果仍在使用 workers.dev 地址，也要把它对应的完整回调地址加入列表。

Add redirect URIs

Google 要求实际请求中的 Redirect URI 与这里登记的地址完全一致，包括 http 或 https、主机名、端口、大小写、路径和末尾斜杠。

保存 Client ID 和 Client Secret

点击 Create。创建完成后立即保存 Client ID 和 Client Secret。Client ID 通常以 .apps.googleusercontent.com 结尾。

Save Client ID and Client Secret

Client Secret 只能放在服务端环境中，不能写进前端代码或提交到 Git。

Google 对 Web application 客户端和地址格式的完整要求见 Get your Google API client ID 和 Manage OAuth clients。

配置本地环境

在项目根目录的 .env 中填写：

GOOGLE_CLIENT_ID="你的 Google Client ID"
GOOGLE_CLIENT_SECRET="你的 Google Client Secret"

保存后重启开发服务器：

npm run doctor
npm run dev

登录和注册页面会在两项凭据都存在时启用 Google 登录。只填写 Client ID 不够，因为普通 OAuth 登录需要服务端使用 Client Secret 交换授权码。

配置生产环境

第一次部署完成后，在 .env.production 中填写生产环境使用的凭据：

GOOGLE_CLIENT_ID="生产环境的 Google Client ID"
GOOGLE_CLIENT_SECRET="生产环境的 Google Client Secret"

然后运行：

npm run doctor:remote
npm run deploy:update

部署时，Client ID 会作为 Worker Variable，Client Secret 会作为加密 Secret 同步到 Cloudflare。不要只修改 Cloudflare Dashboard；Saavo 后续仍以 .env.production 为生产配置来源。

如果还没有完成第一次部署，可以暂时留空 OAuth 变量并运行 npm run deploy:init。拿到实际 workers.dev 地址后，将对应的 Origin 和 Redirect URI 添加到 Google Cloud，再填写 .env.production 并运行 npm run deploy:update。

以后改用自定义域名时，需要同时完成三件事：

  1. 在 Google Cloud 的 Authorized JavaScript origins 中加入新 Origin；
  2. 在 Authorized redirect URIs 中加入新域名对应的完整 Google 回调地址；
  3. 确认 .env.production 中的 VITE_SITE_URL 已经是新 Origin，并重新部署。

是否开启 Google One Tap

普通 Google 登录配置完成后，用户已经可以从登录或注册页面进入 Google 授权。One Tap 是额外功能，默认关闭：

config/deploy.ts
auth: {
    enableGoogleOneTap: false,
},

需要启用时改为：

config/deploy.ts
auth: {
    enableGoogleOneTap: true,
},

启用前确认当前页面的 Origin 已经登记在 Google Cloud 的 Authorized JavaScript origins 中。正式环境必须使用 HTTPS；本地开发可以使用 http://localhost 或本机回环地址。保存配置后，本地重启 npm run dev，生产环境运行 npm run deploy:update。

One Tap 可能被浏览器隐私设置、第三方 Cookie 策略、FedCM 设置或扩展拦截。它没有出现时，登录页上的普通 Google 登录仍应可用，不要把 One Tap 是否弹出作为唯一验收标准。

验证 Google 登录

至少完成下面几项：

  1. 打开登录页，确认能看到 Google 登录入口；
  2. 点击入口，确认 Google 显示的应用名称和请求权限正确；
  3. 同意登录，确认浏览器回到 Saavo，并成功建立登录会话；
  4. 退出后用同一个 Google 账号再次登录，确认不会重复创建用户；
  5. 使用另一个允许访问该应用的 Google 账号测试新用户注册；
  6. 如果开启了 One Tap，再用未登录本站但已登录 Google 的浏览器单独测试提示框。

本地、workers.dev 和正式域名使用不同 Origin，至少要在最终对外使用的域名上完整测试一次。

常见问题