src/lib/plugins/auth/github.ts

src/lib/plugins/auth/github.ts

GitHub OAuth 认证插件，支持通过 GitHub 账号登录。

概述

该插件基于 NextAuth.js 的 GitHub Provider，集成 GitHub OAuth 认证流程。

主要导出

githubPlugin

认证插件实例，实现了 AuthPlugin 接口。

import { githubPlugin } from "@/lib/plugins/auth/github";

功能特性

用户信息映射

从 GitHub 用户资料中提取以下信息：

GitHub 字段映射字段说明
ididGitHub 用户 ID
name 或 loginname用户显示名称
emailemail用户邮箱
avatar_urlimage头像 URL
loginusernameGitHub 用户名（用于显示）
logingithubUsernameGitHub 用户名（不可变，用于贡献者归属）

用户名处理

  • 使用 GitHub login 作为用户名
  • 存储两份：

- username - 可修改的显示用户名 - githubUsername - 不可变的原始 GitHub 用户名（用于贡献者归属追踪）

环境变量

需要配置以下环境变量：

# GitHub OAuth App 配置
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

获取方式

  1. 登录 GitHub
  2. 进入 Settings → Developer settings → OAuth Apps
  3. 点击 "New OAuth App"
  4. 填写应用信息：

- Authorization callback URL: http://localhost:3000/api/auth/callback/github（开发环境） - 生产环境使用实际域名

使用方式

前端登录调用

import { signIn } from "next-auth/react";

await signIn("github");

配置启用

在 prompts.config.ts 中启用：

export default defineConfig({
  auth: {
    providers: ["github", "credentials"],
    allowRegistration: true,
  },
  // ...
});

用户创建流程

  1. 用户点击 GitHub 登录按钮
  2. 重定向到 GitHub 授权页面
  3. 用户授权后，GitHub 回调到应用
  4. NextAuth 处理 OAuth 回调
  5. 调用自定义 Prisma Adapter 创建用户
  6. 用户名处理：

- 优先使用 GitHub login 作为用户名 - 检查是否存在同名的无主账户 - 如果存在，认领该账户 - 如果不存在，创建新用户

注意事项

  1. GitHub 用户名被存储为不可变字段，用于贡献者归属
  2. 支持认领预创建的无主账户（用于贡献者关联）
  3. 如果用户修改了 GitHub 用户名，githubUsername 保持不变
  4. 需要用户邮箱是公开的，或在 OAuth 授权时允许访问
  5. 生产环境必须使用 HTTPS 回调 URL
← 返回目录