原创

GitHub Login 对接配置指南

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

1. 前提条件

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

2. 创建 GitHub OAuth App

2.1 进入 OAuth Apps 页面

登录 GitHub
点击右上角头像 → Settings（设置）
左侧菜单滚动到底部，点击 Developer settings（开发者设置）
点击 OAuth Apps
点击 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 详情页：

Client ID — 页面顶部直接显示，即 GITHUB_CLIENT_ID
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 测试步骤

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

7.3 使用多个 GitHub 账号测试

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

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

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

8. 生产环境部署

8.1 创建生产环境 OAuth App

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

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

字段	值
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：

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

9. 常见问题排查

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

原因：回调 URL 不匹配。

解决：

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

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

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

解决：

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

问题：`GITHUB_CLIENT_ID` 或 `GITHUB_CLIENT_SECRET` 未生效

解决：

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

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

解决：

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

问题：提示 "Bad credentials" 错误

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

解决：

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

环境变量汇总

# .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 操作
本项目需求	✅ 适合	❌ 过度设计