6.1.3 GitHub 登录怎么接——GitHub OAuth 实战

一句话破题

GitHub OAuth 是开发者最友好的登录方式——注册应用只需要 2 分钟，配置比 Google 简单得多。

为什么推荐 GitHub 登录

特性	GitHub	Google
注册复杂度	简单	需要项目+同意屏幕
审核要求	无	测试模式需添加用户
开发者友好度	极高	一般
适用场景	技术产品	通用产品

步骤一：创建 GitHub OAuth App

1. 登录 GitHub → 右上角头像 → Settings
2. 左侧菜单最底部 → Developer settings
3. 选择 OAuth Apps → New OAuth App
4. 填写应用信息：

字段	开发环境	生产环境
Application name	My Dev App	My Production App
Homepage URL	http://localhost:3000	https://your-domain.com
Authorization callback URL	http://localhost:3000/api/auth/callback/github	https://your-domain.com/api/auth/callback/github

5. 点击 Register application
6. 创建成功后，点击 Generate a new client secret
7. 复制 Client ID 和 Client Secret

重要

Client Secret 只显示一次！立即复制保存，否则需要重新生成。

步骤二：配置环境变量

# .env.local
GITHUB_ID=your-github-client-id
GITHUB_SECRET=your-github-client-secret

步骤三：NextAuth 配置

// app/api/auth/[...nextauth]/route.ts
import NextAuth from "next-auth"
import GitHubProvider from "next-auth/providers/github"

const handler = NextAuth({
  providers: [
    GitHubProvider({
      clientId: process.env.GITHUB_ID!,
      clientSecret: process.env.GITHUB_SECRET!,
    }),
  ],
})

export { handler as GET, handler as POST }

获取用户的 GitHub 数据

GitHub 返回的用户信息包含：

interface GitHubProfile {
  id: number
  login: string        // GitHub 用户名
  name: string | null  // 显示名称
  email: string | null // 邮箱（可能为空）
  avatar_url: string   // 头像
  html_url: string     // GitHub 主页
}

获取用户邮箱

有些用户的邮箱是私有的，需要额外配置 scope：

GitHubProvider({
  clientId: process.env.GITHUB_ID!,
  clientSecret: process.env.GITHUB_SECRET!,
  authorization: {
    params: {
      scope: "read:user user:email",
    },
  },
})

在 Callback 中处理

callbacks: {
  async signIn({ user, account, profile }) {
    // profile 包含 GitHub 返回的原始数据
    const githubProfile = profile as {
      login: string
      html_url: string
    }
    
    console.log("GitHub 用户名:", githubProfile.login)
    console.log("GitHub 主页:", githubProfile.html_url)
    
    return true
  },
}

同时支持 Google 和 GitHub

import NextAuth from "next-auth"
import GoogleProvider from "next-auth/providers/google"
import GitHubProvider from "next-auth/providers/github"

const handler = NextAuth({
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
    GitHubProvider({
      clientId: process.env.GITHUB_ID!,
      clientSecret: process.env.GITHUB_SECRET!,
    }),
  ],
})

export { handler as GET, handler as POST }

用户点击登录时，NextAuth 会自动显示所有可用的登录选项。

GitHub Apps vs OAuth Apps

GitHub 提供两种应用类型：

特性	OAuth Apps	GitHub Apps
用途	用户认证	仓库/组织集成
权限粒度	粗	细
安装方式	用户授权	组织/仓库安装
NextAuth 支持	✅	需额外配置

对于登录场景，使用 OAuth Apps 即可。

常见问题

回调地址错误

The redirect_uri MUST match the registered callback URL

解决：确保 GitHub OAuth App 中的 callback URL 与 NEXTAUTH_URL 完全一致，包括协议（http/https）和端口号。

获取不到用户邮箱

原因：用户在 GitHub 设置中将邮箱设为私有

解决：

1. 添加 user:email scope
2. 或者在注册流程中要求用户手动填写邮箱