使用 Google 登录（OAuth）

四个角色：用户、浏览器、你的服务器、Google

当用户点击"使用 Google 登录"时，发生了什么：

1. 你的服务器将浏览器重定向到一个带有你的 client ID 和回调 URL 的 Google 链接。
2. Google 询问用户"是否允许该应用查看你的邮箱？"用户点击允许。
3. Google 将浏览器重定向回你的回调 URL，并附带一个临时的授权码。
4. 你的服务器拿到这个授权码，携带 client secret 向 Google 发送 POST 请求，换回一个ID token——一个包含用户邮箱、姓名、Google 用户 ID 等信息的 JWT。
5. 你的服务器验证 JWT 签名（证明它确实来自 Google），创建会话，设置 cookie，重定向到你的应用。

client secret 永远不会离开你的服务器。授权码是一次性的。会话 cookie 是你的应用后续使用的凭证。每个环节都有其特定的安全属性。

console.cloud.google.com

登录 Google Cloud Console，创建一个新项目（左上角"选择项目" → "新建项目"），用你的应用名称命名。该项目是你在 Google Cloud 上所有相关资源的容器。

使用 OAuth 无需开启计费——只有付费的 Google API 才需要绑定账单。登录功能是免费的。

用户授权时看到的界面

在项目中，进入 APIs & Services → OAuth consent screen，选择 External 用户类型（Internal 仅适用于 Google Workspace 域名）。需要配置：

• App name：用户看到的名称（如"登录到 AppName"）。
• User support email：一个你会实际查看的真实邮箱地址。
• Authorized domains：你的生产域名（例如 yourapp.com）。
• Developer contact email：通常填你自己的邮箱。
• Scopes：基础登录只需申请 email、profile 和 openid，不要申请超出实际需要的权限。

初始状态下应用处于测试模式——只有在同意屏幕设置中列为测试用户的邮箱才能登录，最多可添加 100 个测试用户。上线时需切换到"正式发布"状态（见第 8 步）。

获取 client ID 和 client secret

APIs & Services → Credentials → Create Credentials → OAuth client ID。

• Application type：选 Web application。
• Name：仅供内部识别，用户不可见。
• Authorized JavaScript origins：你的应用 URL。开发环境填 http://localhost:3000，生产环境填 https://yourapp.com，所有环境都要添加。
• Authorized redirect URIs：Google 回传授权码的地址。开发环境通常是 http://localhost:3000/api/auth/callback/google，生产环境是 https://yourapp.com/api/auth/callback/google。必须完全匹配——末尾斜杠、http 与 https、端口号，一个都不能差。

点击创建。Google 会显示你的 Client ID（以 .apps.googleusercontent.com 结尾的长字符串）和 Client Secret（较短，以 GOCSPX- 开头）。将两者复制到你的后端 env 文件中：

GOOGLE_CLIENT_ID=...apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...

NextAuth / Auth.js / Passport / Clerk——选一个

你可以手写 HTTP 调用来实现 OAuth，但几乎没有必要这样做。标准库已经处理了 state 参数（防 CSRF）、JWT 验证、会话管理以及大量边界情况。针对常见技术栈：

• Next.js：next-auth（即 Auth.js），在一个文件里配置好 provider 就行。
• Express / Node：Passport.js 配合 passport-google-oauth20 策略。
• Django：django-allauth。
• Rails：omniauth + omniauth-google-oauth2。
• 任何现代框架：Clerk、Auth0、Supabase Auth——Auth 即服务，支持 Google 及其他十多个 provider。

以 Next.js 中的 Auth.js 为例，配置大致如下：

import GoogleProvider from "next-auth/providers/google";

export const authOptions = {
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    }),
  ],
};

加上标准的 Auth.js 路由处理器就够了——二十行代码，一个可用的登录按钮。

首次登录创建记录，后续登录查找记录

OAuth 回调成功后，你拿到了一个经过验证的邮箱和 Google 用户 ID。处理逻辑如下：

1. 按 Google ID 在数据库中查找用户。如果找到，该用户即为当前会话用户。
2. 如果没找到，按邮箱查找。如果找到，将 Google 账号关联到该用户（这处理了"先用邮箱密码注册、后来改用 Google 登录"的情况）。
3. 如果两者都没有匹配，则用该邮箱、姓名和 Google ID 创建新用户记录。

将 Google 用户 ID 与邮箱分开存储。邮箱地址在 Google 端理论上可能变更，但 Google ID 永远不变。

开发阶段使用测试用户列表

同意屏幕处于测试状态时，只有添加到测试用户列表中的邮箱才能登录。将你自己的 Google 账号添加进去，就可以在本地开发服务器上点击"使用 Google 登录"并完成整个流程。

Google 首次呈现的同意屏幕会显示你的应用名称、申请的权限范围，以及"此应用未经验证"的警告（测试模式下）。点击"高级 → 转到 AppName（不安全）"即可继续。正式发布后真实用户不会看到这条警告；在此之前，每个测试用户都会看到。

"不安全"警告仅在测试阶段出现

要为真实用户去掉"未经验证"的警告，需要提交应用进行验证。在 OAuth 同意屏幕页面，点击发布应用 → 提交验证。Google 会审查你的主页、隐私政策以及申请的权限范围。

对于基础权限范围（email、profile、openid），验证通常是自动完成的，往往立即生效。对于敏感权限范围（Gmail 访问、Drive 访问等），验证可能需要数周时间，并需通过安全评估。除非有真实的产品需求，否则坚持使用基础权限范围即可。

验证通过后，"不安全"警告消失，100 个测试用户的上限解除，全球任何 Google 用户都可以登录。