🔐 使用 NextAuth 实现 OAuth / Credentials 登录 —— Web 身份的流浪与归宿

"在互联网的浩瀚星海中，每一个用户都渴望一个安全的港湾。NextAuth.js 就是那座灯塔，为你指引认证之路。"

🧭 为什么要用 NextAuth.js？

在构建现代 Web 应用时，"你是谁"是一个必须回答的问题。毕竟：

如果你不是管理员，怎么能删数据？
如果你不是本人，怎么能改密码？
如果你不是登录用户，怎么能白嫖功能！

NextAuth.js 是一个用于 Next.js 应用的身份认证解决方案，支持：

OAuth 登录（Google、GitHub、Facebook......）
自定义账号密码（Credentials）
JWT 或数据库会话
多种适配器与扩展能力

它就像 Web 身份系统中的瑞士军刀🔪，能刚能柔，能 OAuth 也能手动登录。

⚙️ 安装：喂饱你的项目

lua 复制代码

npm install next-auth

📁 项目结构神秘地图

bash 复制代码

/pages
  └── api
       └── auth
            └── [...nextauth].js   👈 认证的心脏

这个 [...nextauth].js 文件是 NextAuth 的路由入口，是认证逻辑的主控大脑 🧠。

🌈 实现 OAuth 登录（以 GitHub 为例）

1. 去 GitHub 注册 OAuth App

填写回调地址，例如：

bash 复制代码

http://localhost:3000/api/auth/callback/github

拿到 Client ID 和 Client Secret

2. 配置 `.env.local`

ini 复制代码

GITHUB_ID=你的ClientID
GITHUB_SECRET=你的ClientSecret
NEXTAUTH_SECRET=一串超级随机的密钥

3. 配置 `[...nextauth].js`

arduino 复制代码

import NextAuth from "next-auth";
import GitHubProvider from "next-auth/providers/github";

export default NextAuth({
  providers: [
    GitHubProvider({
      clientId: process.env.GITHUB_ID,
      clientSecret: process.env.GITHUB_SECRET,
    }),
  ],
  secret: process.env.NEXTAUTH_SECRET,
});

🧪 实现 Credentials 登录（账号密码）

适用于你想自己掌控身份验证逻辑，比如邮箱+密码登录机制。

php 复制代码

import NextAuth from "next-auth";
import CredentialsProvider from "next-auth/providers/credentials";

export default NextAuth({
  providers: [
    CredentialsProvider({
      name: "Credentials",
      credentials: {
        email: { label: "Email", type: "text" },
        password: { label: "Password", type: "password" }
      },
      async authorize(credentials) {
        // 模拟数据库验证
        const user = {
          id: "1",
          name: "Alice",
          email: "alice@example.com"
        };

        if (
          credentials.email === user.email &&
          credentials.password === "password123"
        ) {
          return user;
        }

        return null; // 返回 null 表示认证失败
      }
    })
  ],
  pages: {
    signIn: '/login'  // 自定义登录页（可选）
  },
  secret: process.env.NEXTAUTH_SECRET
});

🔐 在前端使用登录按钮

javascript 复制代码

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

export default function AuthButton() {
  const { data: session } = useSession();

  if (session) {
    return (
      <>
        <p>欢迎，{session.user.name} 👋</p>
        <button onClick={() => signOut()}>退出登录</button>
      </>
    );
  }

  return (
    <>
      <button onClick={() => signIn("github")}>使用 GitHub 登录</button>
      <button onClick={() => signIn("credentials", {
        email: "alice@example.com",
        password: "password123"
      })}>使用账号密码登录</button>
    </>
  );
}

🧬 会话机制：JWT vs 数据库存储

NextAuth 默认使用 JWT（Json Web Token） 来存储会话信息。如果你想保存会话到数据库，还可以启用 adapter，比如 Prisma。

JWT 的好处：

无状态，轻量
存储在 Cookie 中，自动发送
可扩展：你可以在 token 中添加自定义字段

javascript 复制代码

callbacks: {
  async jwt({ token, user }) {
    if (user) {
      token.role = "admin"; // 添加角色信息
    }
    return token;
  },
  async session({ session, token }) {
    session.user.role = token.role;
    return session;
  }
}

🪄 登录流程图解（用 emoji 表达）

scss 复制代码

🧑 用户点击登录按钮
⬇️
🔀 跳转到 OAuth 提供商（如 GitHub）
⬇️
✅ 授权成功 → 获取令牌
⬇️
🔐 创建会话（JWT 或数据库）
⬇️
📦 将用户信息保存在 session
⬇️
🧞‍♂️ 客户端用 useSession() 获取身份

🧙‍♂️ 高级玩法提示

支持多种 OAuth 提供商同时接入（Google + GitHub + Twitter）
支持多语言国际化
支持自定义登录页（pages.signIn）
支持魔法链接（Email Provider）
支持自定义数据库适配器（Prisma、MongoDB）

📌 小贴士

情况	建议
本地开发调试失败	检查回调 URL 是否一致
登录后页面跳转问题	使用 `redirect: false` 捕获重定向
Session 丢失	检查 Cookie 是否配置正确（尤其是跨域）
使用 https	在 production 中设置 `NEXTAUTH_URL`

🧦 结语：Web 身份的诗意归宿

我们在构建 Web 的过程中，身份认证就像一双鞋 ------ 你不想它太紧（用户体验差），也不想它太松（安全性低）。NextAuth.js 就是那双量脚定制的皮鞋，既优雅又安全。

"在这片由组件、API 和状态组成的数字原野，一个用户的登录，就像他终于找回了自己。"

🎁 彩蛋：一张图看懂 NextAuth 登录逻辑

csharp 复制代码

[User Clicks Sign In]
        ↓
[NextAuth Redirects to Provider]
        ↓
[OAuth Login Page (e.g. GitHub)]
        ↓
[Callback to /api/auth/callback]
        ↓
[Token Issued + Session Created]
        ↓
[Frontend uses useSession()]

🧠 你已完成"NextAuth 入门修仙"第一阶段。

下一步？加入数据库、权限系统、RBAC，走上全栈认证之路！

📚 参考资料