GitHub Login 对接配置指南

本文档详细说明如何为 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）

💡 直达链接：github.com/settings/ap...

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. 访问 github.com/settings/ap...
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 或 .envGITHUB_CLIENT_ID="Iv1.xxxxxxxxxxxx"         # GitHub OAuth App Client IDGITHUB_CLIENT_SECRET="xxxxxxxxxxxxxxxx"      # GitHub OAuth App Client SecretNEXTAUTH_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 是最佳选择，设置简单且功能完全满足需求。