Next.js NextAuth.js 认证示例实战auth.ts 配置、Middleware 会话保护与 Server Actions 登录【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js本篇指南围绕 Next.js 仓库中的 auth 认证示例 展开该示例演示了如何在 App Router 中使用 NextAuth.jsv5 beta实现基于 GitHub OAuth 的完整登录、登出与会话保护。读完本文你将掌握create-next-app一键引导该示例的方法、auth.ts中 NextAuth 工厂函数的导出结构、Route Handler 与 Middleware 各自在认证链路中的职责以及 Server Actions 表单实现无客户端 JS 登录的写法。使用 create-next-app 引导认证示例README 说明可以通过create-next-app将示例快速脚手架化支持 npm、Yarn、pnpm、Bun 四种包管理器命令如下npx create-next-app --example auth auth-appyarn create next-app --example auth auth-apppnpm create next-app --example auth auth-appbunx create-next-app --example auth auth-app执行后会在auth-app目录下生成完整项目依赖与脚本定义见 package.json核心依赖为nextlatest、next-auth^5.0.0-beta.4、react与react-domlatest开发脚本为标准的next dev/next build/next start三条命令示例基于 App Routerapp/目录与 TypeScript未引入任何额外的 UI 框架。示例整体结构该示例刻意保持最小化全部认证逻辑由 4 个文件承载文件职责清晰文件职责auth.tsNextAuth 唯一配置源导出auth、signIn、signOut与 API 处理器middleware.ts在请求进入业务逻辑前拦截并校验会话app/api/auth/[...nextauth]/route.ts把 NextAuth 的GET/POST处理器挂到 App Router 的 Route Handler 上app/page.tsx展示登录状态的页面内嵌 Server Actions 登录/登出表单其中 tsconfig.json 通过paths配置了/*: [./*]别名因此源码中的import { auth } from /auth直接指向项目根目录的 auth.ts而不是app/目录下的文件——这是理解整个示例导入关系的前提。auth.tsNextAuth 的唯一配置源整个示例的核心只有 auth.ts 这一个文件import NextAuth from next-auth; import GitHub from next-auth/providers/github; export const { handlers: { GET, POST }, auth, signIn, signOut, } NextAuth({ providers: [GitHub], });从源码结构可以看出几个关键设计NextAuth()是工厂函数。它接收配置对象返回一个包含多个可导出成员的实例而不是直接返回一个默认导出的对象。handlers.GET与handlers.POST是 HTTP 处理器专门用于对接 App Router 的 Route Handler见下一节。这里只取出了GET、POST两个方法说明该示例只用到 OAuth 回调与登录发起这两类 HTTP 交互。auth、signIn、signOut是可在服务端直接调用的函数auth用于读取当前会话signIn发起登录signOut结束会话。providers: [GitHub]声明了唯一的登录提供方为 GitHub OAuth登录成功后session.user.email会携带 GitHub 账号邮箱页面正是用它来显示Welcome信息。值得注意的是该文件没有配置数据库 Adapter示例依赖 NextAuth 的 JWT 会话模式、也没有显式配置trustHost等选项体现了示例的最小可用定位。Route Handler把 NextAuth 挂到 App Router 上app/api/auth/[...nextauth]/route.ts 只有一行export { GET, POST } from /auth;它把 auth.ts 中解构出的GET、POST处理器原样转发到/api/auth/[...nextauth]这个动态路由上。这样 NextAuth 的 OAuth 发起、回调与 CSRF 校验等流程就全部走 App Router 的 Route Handler 机制无需兼容 Pages Router 的 API Routes 写法。middleware.ts全局会话保护middleware.ts 是整个示例中保护路由的关键export { auth as default } from ./auth; // Optionally, dont invoke Middleware on some paths export const config { matcher: [/((?!api|_next/static|_next/image|favicon.ico).*)], };export { auth as default }NextAuth v5 的auth函数本身就是一个符合 Next.js Middleware 签名的函数因此直接作为默认导出Next.js 会在每次匹配的请求上执行它完成会话读取。matcher正则/((?!api|_next/static|_next/image|favicon.ico).*)是一个带否定先行断言的模式含义是匹配除以下前缀之外的所有路径api认证 API 自身必须放行否则登录流程无法完成、_next/static与_next/image构建产物与图片优化接口、favicon.ico。这样可以避免对静态资源和认证端点做无谓的会话检查。从该结构可以推断示例对/首页采取了允许访问但内容依赖会话的策略auth在 Middleware 中负责会话上下文的注入与校验而是否登录的展示逻辑则由页面组件自己根据session决定。页面组件Server Actions 登录/登出app/page.tsx 展示了 App Router 下完全不需要客户端 JavaScript 的登录/登出交互import { auth, signIn, signOut } from /auth; function SignIn() { return ( form action{async () { use server; await signIn(github); }} pYou are not logged in/p button typesubmitSign in with GitHub/button /form ); } function SignOut({ children }: { children: React.ReactNode }) { return ( form action{async () { use server; await signOut(); }} p{children}/p button typesubmitSign out/button /form ); } export default async function Page() { let session await auth(); let user session?.user?.email; return ( section h1Home/h1 div{user ? SignOut{Welcome ${user}}/SignOut : SignIn /}/div /section ); }实现要点use server指令表单action中的异步函数被标记为 Server Action点击按钮即触发一次服务端函数调用await signIn(github)会发起对 GitHub 的 OAuth 重定向无需编写onClick或任何use client组件。会话读取发生在服务端页面是async服务端组件await auth()直接拿到会话对象session?.user?.email有值时渲染SignOut组件并显示Welcome {email}否则渲染SignIn组件。登出走同样的 Server Action 路径await signOut()在服务端清除会话刷新后页面自动回到未登录状态。页面根布局 app/layout.tsx 仅声明了metadata标题为 Next.js Authentication与标准html/body结构样式 app/globals.css 也只有防止横向滚动的两条规则保证示例聚焦认证本身。部署与所需环境变量README 提供了一键部署入口其部署配置中要求预先提供三个环境变量AUTH_GITHUB_IDGitHub OAuth App 的 Client IDAUTH_GITHUB_SECRETGitHub OAuth App 的 Client SecretAUTH_SECRETNextAuth 用于会话加签/加密的密钥。也就是说本地运行该示例前同样需要先在一个 GitHub OAuth Application 中创建 App、获得 ID 与 Secret并在环境变量中配置上述三项signIn(github)的重定向流程才能正常完成回调校验。小结这个 examples/auth 示例虽然文件很少但完整覆盖了 App Router 下接入 NextAuth.js v5 的标准链路auth.ts 作为唯一配置源导出处理器与认证函数Route Handler 挂载 NextAuth 的 API 端点middleware.ts 以matcher精确排除静态资源与 API 路径后做全局会话校验页面组件 则用 Server Actions 实现零客户端 JS 的登录与登出。将其作为模板可以在此基础上追加更多 providers、接入数据库 Adapter 或收紧matcher来匹配实际业务的受保护路由需求。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考