> ## 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/docs/web/ship-in-5-minutes.md)

[设置数据库](https://supastack.dev/zh/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/docs/web/github-sign-in.md)

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


如果你想继续完成设置，可以阅读《[添加 GitHub 登录](https://supastack.dev/zh/docs/web/github-sign-in.md)》。


## 下一篇

[添加 GitHub 登录](https://supastack.dev/zh/docs/web/github-sign-in.md)