跳转到内容
supastack
浏览文档
WebTanStack Start

For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh/docs/tanstack/google-sign-in.md (or send Accept: text/markdown).

添加 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-tanstack/.env.local 并重启开发服务器。

一个项目足以支撑整个产品：同一个 Google Cloud 项目之后还会托管你的 Cloud Run 部署，移动端登录也经由同一个 Web 后端——你无需为每个平台或功能单独创建客户端。

创建 Google Cloud 项目

1. 打开 console.cloud.google.com 并用你的 Google 账户登录。

2. 点击顶栏中的项目下拉菜单（Google Cloud 徽标旁），选择 New Project。

3. 给它起个名字——产品名即可——然后点击 Create。登录凭据不需要组织、银行卡或结算账户。

预期结果：控制台重新加载到新项目，顶栏显示它的名字。当你进行到部署指南时复用这个项目，而不是再建一个。

创建 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-tanstack/.env.local——TanStack Start 读取的是这个文件，而不是根目录的 .env——并设置下面三行。AUTH_GOOGLE_ENABLED=true 打开按钮；客户端凭据对用于标识你的 Google Cloud 客户端。

Client Secret 仅限服务端：它绝不能出现在 NEXT_PUBLIC_ 或 EXPO_PUBLIC_ 变量中，也绝不能提交到 Git。生产环境中，请在托管方的密钥存储中设置同样的三个名称，而不是放在 env 文件里。

编辑后重启开发服务器——环境变更只在启动时读取。

# apps/web-tanstack/.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 登录》。