Saavo

配置 GitHub OAuth

创建 GitHub OAuth App，配置本地与生产回调地址，并将 Client ID 和 Client Secret 接入 Saavo。

Saavo 已经实现了 GitHub 登录流程。你只需要在 GitHub 注册一个 OAuth App，把回调地址和两项凭据配置正确，不需要自己编写授权、回调或读取用户资料的代码。

配置完成后，登录和注册页面会自动显示 GitHub 入口。用户授权时，模板会申请 read:user 和 user:email，用于读取 GitHub 用户资料和邮箱，不会申请仓库权限。

开始前先确定地址

GitHub 授权完成后，需要把用户送回 Saavo 的 GitHub 回调接口。默认路径在 config/deploy.ts 中：

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

最终回调地址由“站点 Origin + 回调路径”组成。以本文项目为例：

环境站点 OriginAuthorization callback URL
本地http://127.0.0.1:5173http://127.0.0.1:5173/api/auth/oauth2/github
首次部署终端显示的 workers.dev 地址https://<实际的 workers.dev 域名>/api/auth/oauth2/github
正式域名https://webpagetopdf.devhttps://webpagetopdf.dev/api/auth/oauth2/github

先运行一次 npm run dev，以终端实际显示的地址为准。如果端口不是 5173，回调地址中的端口也要一起修改。正式环境同样以 .env.production 中的 VITE_SITE_URL 为准。

回调地址不包含语言路径

不要在地址中加入 /zh-Hans、/en 等语言路径，也不要在结尾添加 /。模板使用的固定路径就是 /api/auth/oauth2/github。

创建 GitHub OAuth App

打开 OAuth Apps

登录 GitHub，点击右上角头像，依次进入 Settings → Developer settings → OAuth Apps，然后点击 New OAuth App。第一次创建时，按钮可能显示为 Register a new application。

register a new OAuth app

团队项目可以在拥有管理权限的 GitHub Organization 下创建，避免应用长期绑定在某位成员的个人账号中。个人项目直接创建在自己的账号下即可。

填写应用信息

按下面的方式填写：

GitHub 字段本地开发示例正式项目示例
Application nameWebpageToPDF LocalWebpageToPDF
Homepage URLhttp://127.0.0.1:5173https://webpagetopdf.dev
Application description可选，简要说明用途可选，简要说明用途
Authorization callback URLhttp://127.0.0.1:5173/api/auth/oauth2/githubhttps://webpagetopdf.dev/api/auth/oauth2/github

GitHub 当前允许一个 OAuth App 添加多个回调地址。个人项目可以先创建一个应用，再通过 Add callback URL 同时加入本地地址、workers.dev 地址和正式域名。对环境隔离要求较高的团队，也可以分别创建开发和生产应用，让两套环境使用不同的 Client Secret。

不需要启用 Device Flow。Saavo 使用的是网站授权码流程，登录完成后由浏览器返回回调接口。

注册并保存凭据

点击 Register application，进入应用详情页面。

OAuth app details

可以在这个页面补全剩余的信息，例如 Logo、Description 等。

复制 Client ID，再点击 Generate a new client secret 创建 Client Secret。

Client Secret 只交给服务端使用，应立即保存到密码管理器或项目的环境文件中。不要写进 config/deploy.ts、浏览器代码、截图或 Git 仓库。

检查回调地址

在应用设置中确认每个环境都登记了完整回调地址，并关闭不需要的通配符匹配。Saavo 的回调路径是固定的，没有必要允许任意子域名或子路径。

GitHub 对回调地址进行匹配。协议、主机名、端口或路径不同，都可能导致 redirect_uri_mismatch。localhost 与 127.0.0.1 也不是同一个主机名，不要混用。

确认登录可用性

完成注册和凭据配置后，用户即可授权此 GitHub OAuth App。本文的登录接入不需要 Google 式的测试用户名单，也没有 Publish app 发布审核步骤。网站发布前，请完成下文的完整登录验证。

GitHub 官方的最新界面和字段说明见 Creating an OAuth app，回调地址匹配规则见 Authorizing OAuth apps。

配置本地环境

打开项目根目录的 .env，填写刚才得到的两项内容：

GITHUB_CLIENT_ID="你的 GitHub Client ID"
GITHUB_CLIENT_SECRET="你的 GitHub Client Secret"

保存后重启开发服务器：

npm run doctor
npm run dev

doctor 不再显示 GitHub OAuth is not configured，说明两项变量都已读取。只填写其中一项时，doctor 会提示另一项缺失，登录页面也不会启用 GitHub 登录。

不要提交 .env

.env 已经被模板加入 .gitignore。Client ID 会出现在授权请求中，不属于密码；Client Secret 则必须保密。为了避免两者配置错位，本文仍建议把它们放在同一个环境文件中管理。

配置生产环境

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

GITHUB_CLIENT_ID="生产环境的 GitHub Client ID"
GITHUB_CLIENT_SECRET="生产环境的 GitHub Client Secret"

然后运行：

npm run doctor:remote
npm run deploy:update

部署脚本会把 Client ID 作为 Worker Variable，把 Client Secret 作为加密 Secret 同步到 Cloudflare。不要只在 Cloudflare Dashboard 中手工填写，否则下次运行 deploy:update 时，本地记录和远程环境可能不一致。

如果项目还没有完成第一次部署，可以先让 OAuth 变量保持空白，运行 npm run deploy:init。拿到实际的 workers.dev 地址后，把它的完整回调地址添加到 GitHub OAuth App，再填写 .env.production 并运行 npm run deploy:update。

绑定 webpagetopdf.dev 后，还要把下面的地址加入 OAuth App：

https://webpagetopdf.dev/api/auth/oauth2/github

只修改 VITE_SITE_URL 而不更新 GitHub 后台，用户会在授权返回时遇到回调地址不匹配。

验证 GitHub 登录

不要只检查按钮是否出现。请使用一个真实 GitHub 账号走完下面的流程：

  1. 打开站点的登录页，确认能看到 GitHub 登录入口；
  2. 点击入口，确认浏览器跳转到 github.com，页面显示的是刚创建的 OAuth App；
  3. 查看授权页面申请的权限，不应出现仓库读写权限；
  4. 同意授权，确认浏览器回到 Saavo，并已经处于登录状态；
  5. 退出登录，再用同一个 GitHub 账号登录一次，确认不会重复创建用户；
  6. 再用一个 GitHub 邮箱未公开的账号测试，确认模板仍能通过 user:email 读取可用邮箱。

本地和正式域名要分别测试。生产配置正确，不能证明本地端口对应的回调地址也正确。

常见问题