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 回呼 API。預設路徑位於 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。

註冊新的 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 使用網站授權碼流程，登入完成後，由瀏覽器返回回呼 API。

註冊並儲存驗證資訊

按下 Register application，進入應用程式詳細資訊頁面。

OAuth App 詳細資訊

可以在這個頁面補齊其他資訊，例如 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 讀取可用的地址。

本機與正式網域都要分別測試。正式環境設定正確，不能證明本機連接埠對應的回呼網址也正確。

常見問題