src/lib/auth/index.ts

src/lib/auth/index.ts

NextAuth.js 认证配置模块，提供完整的用户认证解决方案。

概述

该模块是整个应用的认证核心，负责：

  • 集成 NextAuth.js 5 (beta)
  • 配置多种认证提供者（credentials, GitHub, Google, Azure, Apple）
  • 自定义 Prisma Adapter 处理用户创建
  • JWT 和 Session 回调管理
  • 用户名生成和唯一性处理

主要导出

handlers

NextAuth 的 API 路由处理器，用于处理认证请求。

// 在 app/api/auth/[...nextauth]/route.ts 中使用
export const { GET, POST } = handlers;

signIn

登录函数，用于程序化触发登录流程。

import { signIn } from "@/lib/auth";

await signIn("github");

signOut

登出函数，用于程序化触发登出流程。

import { signOut } from "@/lib/auth";

await signOut();

auth

获取当前会话的辅助函数。

import { auth } from "@/lib/auth";

const session = await auth();

核心功能

1. 用户名生成

自动生成唯一的用户名：

  • 首先尝试使用邮箱前缀（@ 之前的部分）
  • 如果太短（少于 3 个字符），使用用户姓名
  • 确保最小长度为 3 个字符
  • 检查用户名是否已存在，自动添加序号后缀

2. 自定义 Prisma Adapter

扩展默认的 PrismaAdapter，添加以下功能：

  • 自定义用户名处理
  • GitHub 用户名存储（不可变）
  • 支持认领无主账户（unclaimed accounts）
  • 确保 GitHub 用户名唯一性

3. 动态提供者配置

支持从配置文件动态加载认证提供者：

  • 支持新的 providers 数组配置
  • 向后兼容旧的 provider 字符串配置
  • 默认使用 credentials 提供者

4. JWT 回调

处理 JWT Token 的生命周期：

  • 登录时从数据库查询用户信息
  • 后续请求验证用户是否存在
  • 支持显式更新（trigger: "update"）
  • 用户被删除时使 Token 失效

5. Session 回调

将 Token 数据注入到 Session 中：

  • 用户 ID
  • 用户角色
  • 用户名
  • 语言设置
  • 头像 URL

类型扩展

模块扩展了 NextAuth 的类型定义：

// Session 类型扩展
interface Session {
  user: {
    id: string;
    email: string;
    name?: string | null;
    image?: string | null;
    role: string;
    username: string;
    locale: string;
  };
}

// JWT 类型扩展
interface JWT {
  id: string;
  role: string;
  username: string;
  locale: string;
  name?: string | null;
  picture?: string | null;
}

环境要求

需要以下环境变量：

  • AUTH_SECRET - NextAuth 密钥
  • 根据启用的提供者需要相应的 OAuth 配置

注意事项

  1. 插件系统在使用前会自动初始化
  2. 所有用户创建都会通过自定义 Adapter 处理
  3. GitHub 登录用户会存储其 GitHub 用户名用于贡献者归属
  4. 支持认领预创建的无主账户（用于贡献者关联）
← 返回目录