143 lines
3.1 KiB
Markdown
143 lines
3.1 KiB
Markdown
# Google OAuth 快速开始指南
|
||
|
||
## 5 分钟快速集成
|
||
|
||
### 步骤 1: 获取 Google OAuth 凭据
|
||
|
||
1. 访问 [Google Cloud Console](https://console.cloud.google.com/)
|
||
2. 创建新项目或选择现有项目
|
||
3. 在左侧菜单选择 "API 和服务" > "凭据"
|
||
4. 点击 "创建凭据" > "OAuth 客户端 ID"
|
||
5. 选择应用类型为 "Web 应用"
|
||
6. 配置授权重定向 URI：
|
||
```
|
||
http://localhost:3000/api/auth/google/callback
|
||
```
|
||
7. 点击"创建"并复制客户端 ID
|
||
|
||
### 步骤 2: 配置环境变量
|
||
|
||
在项目根目录创建 `.env.local` 文件：
|
||
|
||
```bash
|
||
NEXT_PUBLIC_APP_URL=http://localhost:3000
|
||
NEXT_PUBLIC_GOOGLE_CLIENT_ID=你的客户端ID
|
||
```
|
||
|
||
### 步骤 3: 重启开发服务器
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
### 步骤 4: 测试登录
|
||
|
||
1. 访问 http://localhost:3000/login
|
||
2. 点击 "Continue with Google" 按钮
|
||
3. 选择 Google 账号并授权
|
||
4. 应该会重定向回应用并完成登录
|
||
|
||
## 文件清单
|
||
|
||
已创建的文件：
|
||
|
||
- ✅ `src/lib/oauth/google.ts` - Google OAuth 配置
|
||
- ✅ `src/app/(auth)/login/components/GoogleButton.tsx` - Google 登录按钮组件
|
||
- ✅ `src/app/api/auth/google/callback/route.ts` - OAuth 回调路由
|
||
- ✅ `src/app/(auth)/login/components/login-form.tsx` - 已更新使用 GoogleButton
|
||
|
||
## 工作流程
|
||
|
||
```
|
||
用户点击按钮
|
||
↓
|
||
GoogleButton.handleGoogleLogin()
|
||
↓
|
||
跳转到 Google 授权页面
|
||
↓
|
||
用户授权
|
||
↓
|
||
Google 重定向到 /api/auth/google/callback
|
||
↓
|
||
API 路由提取 code 并重定向到 /login?google_code=xxx
|
||
↓
|
||
GoogleButton.useEffect() 检测到 google_code
|
||
↓
|
||
调用后端登录接口 (thirdType: Google)
|
||
↓
|
||
登录成功，跳转到首页
|
||
```
|
||
|
||
## 后端接口要求
|
||
|
||
后端需要处理以下登录请求：
|
||
|
||
```typescript
|
||
POST /api/auth/login
|
||
|
||
{
|
||
"appClient": "WEB",
|
||
"deviceCode": "设备ID",
|
||
"thirdToken": "Google授权码",
|
||
"thirdType": "GOOGLE"
|
||
}
|
||
```
|
||
|
||
后端需要：
|
||
|
||
1. 使用授权码向 Google 交换 access_token
|
||
2. 使用 access_token 获取用户信息
|
||
3. 创建或更新用户
|
||
4. 返回应用的登录 token
|
||
|
||
## 常见问题
|
||
|
||
### Q: 点击按钮后没有跳转？
|
||
|
||
A: 检查浏览器控制台是否有错误，确认环境变量已正确配置。
|
||
|
||
### Q: 回调后显示错误？
|
||
|
||
A: 检查 Google Cloud Console 中的回调 URL 配置是否正确。
|
||
|
||
### Q: 登录接口调用失败？
|
||
|
||
A: 确认后端接口已实现并支持 Google 登录。
|
||
|
||
## 生产环境部署
|
||
|
||
### 1. 更新 Google OAuth 配置
|
||
|
||
在 Google Cloud Console 添加生产环境回调 URL：
|
||
|
||
```
|
||
https://your-domain.com/api/auth/google/callback
|
||
```
|
||
|
||
### 2. 更新环境变量
|
||
|
||
```bash
|
||
NEXT_PUBLIC_APP_URL=https://your-domain.com
|
||
NEXT_PUBLIC_GOOGLE_CLIENT_ID=生产环境客户端ID
|
||
```
|
||
|
||
### 3. 部署
|
||
|
||
确保在部署平台（Vercel/Netlify）配置了正确的环境变量。
|
||
|
||
## 下一步
|
||
|
||
- [ ] 测试完整的登录流程
|
||
- [ ] 添加错误处理和用户反馈
|
||
- [ ] 实现登出功能
|
||
- [ ] 添加用户信息展示
|
||
- [ ] 考虑添加 Apple 登录
|
||
|
||
## 技术支持
|
||
|
||
如有问题，请参考：
|
||
|
||
- [完整文档](./GoogleOAuth.md)
|
||
- [环境变量配置](./EnvironmentVariables.md)
|
||
- [Google OAuth 官方文档](https://developers.google.com/identity/protocols/oauth2)
|