GitHub OAuth 登录对接配置指南

GitHub OAuth 登录对接配置指南

本文档详细说明如何为 Flexes 项目配置 GitHub OAuth 登录功能。

---

1. 前提条件

• 一个 GitHub 账号
• 项目已部署或本地运行于 http://localhost:3000
• 已配置 NEXTAUTH_URL 和 NEXTAUTH_SECRET 环境变量

---

2. 创建 GitHub OAuth App

2.1 进入 OAuth Apps 页面

1. 登录 GitHub
2. 点击右上角头像 → Settings（设置）
3. 左侧菜单滚动到底部，点击 Developer settings（开发者设置）
4. 点击 OAuth Apps
5. 点击 New OAuth App（新建 OAuth App）

💡 直达链接：https://github.com/settings/applications/new

2.2 填写应用信息

字段	开发环境值	生产环境值
Application name	Flexes (Dev)	Flexes
Homepage URL	http://localhost:3000	https://flexes.work
Application description	（可选）A job platform connecting candidates and employers	同左
Authorization callback URL	http://localhost:3000/api/auth/callback/github	https://flexes.work/api/auth/callback/github

⚠️ Authorization callback URL 必须精确匹配，包括协议（http/https）、域名和路径。

2.3 点击 Register application

注册成功后会进入应用详情页。

---

3. 获取 Client ID 和 Client Secret

在 OAuth App 详情页：

1. Client ID — 页面顶部直接显示，即 GITHUB_CLIENT_ID
2. Client Secret — 点击 Generate a new client secret，即 GITHUB_CLIENT_SECRET

⚠️ Client Secret 只会显示一次！ 请立即复制保存。如果丢失，需要重新生成。

⚠️ 绝对不要将 Client Secret 提交到 Git 或暴露在前端代码中。

---

4. 配置项目环境变量

将获取的值填入项目的 .env.local（或 .env）文件中：

# --- GitHub OAuth ---
GITHUB_CLIENT_ID="你的 Client ID"
GITHUB_CLIENT_SECRET="你的 Client Secret"

已有代码说明

项目中 GitHub OAuth Provider 已完成配置，无需修改代码：

src/lib/auth-options.ts：

GitHub({
  clientId: process.env.GITHUB_CLIENT_ID ?? "",
  clientSecret: process.env.GITHUB_CLIENT_SECRET ?? "",
  allowDangerousEmailAccountLinking: true,
  profile(profile) {
    return {
      id: String(profile.id),
      name: profile.name || profile.login,
      email: profile.email,
      image: profile.avatar_url,
      role: "CANDIDATE",
    };
  },
}),

• 通过 GitHub 登录的新用户默认角色为 CANDIDATE
• 如果用户未设置 GitHub 姓名，则使用 GitHub 用户名（login）
• allowDangerousEmailAccountLinking: true 允许相同邮箱的账号自动关联

---

5. 回调 URL 配置

NextAuth.js v5 使用标准的 OAuth 回调路径：

环境	Authorization callback URL
本地开发	http://localhost:3000/api/auth/callback/github
生产环境	https://flexes.work/api/auth/callback/github

💡 建议：为开发和生产分别创建两个 OAuth App，避免频繁切换回调 URL。

---

6. 权限与数据说明

默认权限（无需额外申请）

GitHub OAuth App 默认请求以下权限：

权限范围	说明	获取的数据
read:user	读取用户资料	id、login、name、avatar_url
user:email	读取用户邮箱	email（主邮箱）

项目使用的用户数据

GitHub 字段	存储到	说明
profile.id	User.providerId	GitHub 用户唯一数字 ID
profile.name / profile.login	User.name	姓名（优先）或用户名（备选）
profile.email	User.email	用户主邮箱
profile.avatar_url	User.avatarUrl	GitHub 头像 URL

关于邮箱隐私

• GitHub 允许用户将邮箱设置为私密
• 如果用户的邮箱为私密，NextAuth 会通过 GitHub API 的 user:email scope 获取主邮箱
• 如果用户没有设置任何公开邮箱，登录可能会失败（当前代码要求邮箱存在）

---

7. 测试流程

7.1 启动本地开发服务器

pnpm dev

7.2 测试步骤

1. 访问 http://localhost:3000/login
2. 点击 Continue with GitHub 按钮
3. 浏览器跳转到 GitHub 授权页面：
   • 显示 App 名称和请求的权限
   • 用户点击 Authorize（授权）
4. 授权成功后自动跳回 Flexes 并完成登录：
   • 新用户：自动创建账号（角色 = CANDIDATE）并创建候选人资料
   • 已有用户：直接登录，并关联 GitHub 信息
5. 验证：
   • 检查数据库 User 表，确认 provider = "github" 和 providerId 已填充
   • 确认 Candidate 表已创建对应记录
   • 确认头像已正确显示

7.3 使用多个 GitHub 账号测试

GitHub OAuth App 对所有 GitHub 用户开放（无需添加测试用户），可以用任意 GitHub 账号测试。

如需退出授权并重新测试：

1. 访问 GitHub → Settings → Applications → Authorized OAuth Apps
2. 找到你的 App，点击 Revoke（撤销）
3. 重新登录时会再次弹出授权页面

---

8. 生产环境部署

8.1 创建生产环境 OAuth App

建议为生产环境单独创建一个 OAuth App：

1. 访问 https://github.com/settings/applications/new
2. 填写信息：

字段	值
Application name	Flexes
Homepage URL	https://flexes.work
Authorization callback URL	https://flexes.work/api/auth/callback/github

8.2 配置生产环境变量

在服务器或部署平台（Vercel、PM2 等）中设置：

GITHUB_CLIENT_ID="生产环境的 Client ID"
GITHUB_CLIENT_SECRET="生产环境的 Client Secret"
NEXTAUTH_URL="https://flexes.work"

8.3 组织级 OAuth App（可选）

如果 Flexes 属于 GitHub Organization，可以在组织下创建 OAuth App：

1. 进入组织页面 → Settings → Developer settings → OAuth Apps
2. 好处：App 归属组织而非个人，适合团队管理

---

9. 常见问题排查

问题：点击 GitHub 登录后出现 "redirect_uri mismatch" 错误

原因：回调 URL 不匹配。

解决：

1. 确认 GitHub OAuth App 中的 Authorization callback URL 与以下值完全一致：
   • 开发：http://localhost:3000/api/auth/callback/github
   • 生产：https://flexes.work/api/auth/callback/github
2. 注意不要有多余的斜杠或空格

---

问题：登录成功但获取不到邮箱

原因：GitHub 用户的邮箱设置为私密，且未设置主邮箱。

解决：

• 引导用户到 GitHub Email Settings 设置一个主邮箱
• 或在 GitHub Email 隐私设置中取消勾选 "Keep my email addresses private"

---

问题：GITHUB_CLIENT_ID 或 GITHUB_CLIENT_SECRET 未生效

解决：

1. 检查 .env.local（优先于 .env）中是否正确设置了变量
2. 重启开发服务器（Ctrl+C → pnpm dev）
3. 确认变量值没有多余的空格或引号问题
4. 确认没有在 .env 和 .env.local 中重复定义（.env.local 优先）

---

问题：登录后跳转到错误页面

解决：

1. 确认 NEXTAUTH_URL 设置正确：
   • 开发：http://localhost:3000
   • 生产：https://flexes.work
2. 确认 NEXTAUTH_SECRET 已设置

---

问题：提示 "Bad credentials" 错误

原因：Client Secret 无效或已过期。

解决：

1. 进入 GitHub OAuth App 设置页面
2. 点击 Generate a new client secret 重新生成
3. 更新 .env.local 中的 GITHUB_CLIENT_SECRET
4. 重启开发服务器

---

环境变量汇总

# .env.local 或 .env
GITHUB_CLIENT_ID="Iv1.xxxxxxxxxxxx" # GitHub OAuth App Client ID
GITHUB_CLIENT_SECRET="xxxxxxxxxxxxxxxx" # GitHub OAuth App Client Secret
NEXTAUTH_URL="http://localhost:3000" # 开发环境
# NEXTAUTH_URL="https://flexes.work" # 生产环境
NEXTAUTH_SECRET="your-random-secret" # NextAuth 加密密钥

---

相关文件

文件	说明
src/lib/auth-options.ts	GitHub Provider 配置
src/lib/auth.ts	NextAuth 主配置，包含 OAuth signIn 回调
src/components/auth/login-form.tsx	登录页 GitHub 按钮
src/components/auth/register-form.tsx	注册页 GitHub 按钮
.env.example	环境变量模板

---

与 GitHub Apps 的区别

特性	OAuth App（当前使用）	GitHub App
创建位置	Settings → Developer settings → OAuth Apps	Settings → Developer settings → GitHub Apps
权限模型	基于 scope	细粒度权限
安装范围	用户级别	可安装到组织/仓库
适用场景	用户登录认证	集成自动化、API 操作
本项目需求	✅ 适合	❌ 过度设计

对于用户登录认证场景，OAuth App 是最佳选择，设置简单且功能完全满足需求。