> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 新增 Google 登入

建立免費的 Google Cloud OAuth 客戶端，並把“使用 Google 繼續”接入應用。

## 初學者演練

前提條件：Web 應用在本地執行（5 分鐘啟動）以及一個已遷移、可存真實賬戶的資料庫（設定資料庫）。你需要一個普通的 Google 賬戶；這裡的一切都是免費的，大約需要 10 分鐘。

快速術語：OAuth 是一種標準——Google 在 Google 的頁面上完成使用者登入，並把證明交給你的應用。Google Cloud 專案是 Google 控制台中存放應用憑據的容器。OAuth 同意螢幕是 Google 在把使用者送回之前展示的頁面。Client ID 用於向 Google 標識你的應用；Client Secret 是它的密碼，只留在伺服器上。

1. 建立 Google Cloud 專案。2. 配置同意螢幕。3. 建立一個 Web OAuth 客戶端並複製其 ID 和 Secret。4. 把三個值貼上到 `apps/web/.env.local` 並重啟開發伺服器。

一個專案足以支撐整個產品：同一個 Google Cloud 專案之後還會託管你的 Cloud Run 部署，移動端登入也經由同一個 Web 後端——你無需為每個平臺或功能單獨建立客戶端。

[5 分鐘啟動 Web 應用](https://supastack.dev/zh-tw/docs/web/ship-in-5-minutes.md)

[設定資料庫](https://supastack.dev/zh-tw/docs/web/setup-database.md)


## 建立 Google Cloud 專案

1. 開啟 [console.cloud.google.com](https://console.cloud.google.com) 並用你的 Google 賬戶登入。

2. 點選頂欄中的專案下拉選單（Google Cloud 徽標旁），選擇 New Project。

3. 給它起個名字——產品名即可——然後點選 Create。登入憑據不需要組織、銀行卡或結算賬戶。

預期結果：控制台重新載入到新專案，頂欄顯示它的名字。當你進行到部署指南時複用這個專案，而不是再建一個。


## 配置 OAuth 同意螢幕

1. 在左側導航中開啟 APIs & Services → OAuth consent screen，點選 Get started。

2. 填寫使用者將看到的 App name（你的產品名），選擇 User support email，受眾選擇 External，填寫開發者聯絡郵箱，一路點選到 Create。

3. 此螢幕無需其他操作：應用只請求預設的 `openid`、`email` 和 `profile` 許可權範圍，不需要額外的 scope 或驗證。

開發期間釋出狀態保持 Testing。在該模式下只有被列入的賬戶可以登入，所以請在 Audience → Test users 下新增你自己的 Gmail 地址——否則 Google 連你都會攔下。產品上線後點選 Publish app；由於沒有請求敏感 scope，釋出不會觸發 Google 的驗證稽核。


## 建立 OAuth 客戶端

1. 開啟 APIs & Services → Credentials → + Create Credentials → OAuth client ID。

2. 將 Application type 設為 Web application，並起一個類似 `supastack local` 的名字。

3. 在 Authorized JavaScript origins 下新增 `http://localhost:3000`。在 Authorized redirect URIs 下新增 `http://localhost:3000/api/auth/callback/google`——這個回撥路徑屬於套件預設的認證引擎 Better Auth：`{APP_URL}/api/auth/callback/google`。

4. 點選 Create，並從對話方塊中複製 Client ID 和 Client Secret。之後可以在客戶端頁面重新檢視，但現在複製能省一步。

生產環境再建立第二個 Web 客戶端（推薦），或在當前客戶端上補充：JavaScript origin `https://yourdomain.com` 和 redirect URI `https://yourdomain.com/api/auth/callback/google`。每個環境使用獨立客戶端意味著洩露的本地金鑰無法觸及生產環境。


## 把值新增到應用中

開啟 `apps/web/.env.local`——Next.js 讀取的是這個檔案，而不是根目錄的 `.env`——並設定下面三行。`AUTH_GOOGLE_ENABLED=true` 開啟按鈕；客戶端憑據對用於標識你的 Google Cloud 客戶端。

Client Secret 僅限服務端：它絕不能出現在 `NEXT_PUBLIC_` 或 `EXPO_PUBLIC_` 變數中，也絕不能提交到 Git。生產環境中，請在託管方的金鑰儲存中設定同樣的三個名稱，而不是放在 env 檔案裡。

編輯後重啟開發伺服器——環境變更只在啟動時讀取。

```
# apps/web/.env.local
AUTH_GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
```


## 驗證與故障排除

開啟 http://localhost:3000/auth，點選 Google 按鈕，完成 Google 的同意螢幕，確認回到應用時已處於登入狀態。

`redirect_uri_mismatch` 表示在 Google 中註冊的 redirect URI 不完全匹配——檢查協議（`http` 還是 `https`）、埠和路徑：它必須以 `/api/auth/callback/google` 結尾，而不是 `/callback/google/` 或帶尾部斜槓的變體。

Access blocked / has not completed the Google verification process 表示同意螢幕仍處於 Testing，而正在登入的賬戶未列入 Test users——在 Audience 部分中新增它。

如果 Google 按鈕缺失，或編輯 `.env.local` 後登入仍然失敗，請重啟開發伺服器。如果啟動失敗並報出某個變數名，說明開關已開啟但客戶端憑據對不完整。

[接下來新增 GitHub 登入](https://supastack.dev/zh-tw/docs/web/github-sign-in.md)

[OAuth 提供商概覽](https://supastack.dev/zh-tw/docs/web/setup-oauth.md)


如果你想繼續完成設定，可以閱讀《[新增 GitHub 登入](https://supastack.dev/zh-tw/docs/web/github-sign-in.md)》。


## 下一篇

[新增 GitHub 登入](https://supastack.dev/zh-tw/docs/web/github-sign-in.md)