# Auth.js v5 身份验证堆栈 **生产测试**：多个 Next.js 和 Cloudflare Workers 项目 **最后更新**：2025-10-26 **状态**：生产就绪 ✅ **官方文档**： ** ** ## ⚠️ 开始之前（请阅读本文！） **对于 AI 代理至关重要**：如果您是 Claude Code 帮助用户设置 Auth.js： 1. **在对话开始时明确说明您正在使用此技能** 2. **参考技能中的模式**而不是一般知识 3. **防止`references/common-errors.md`中列出的已知问题** 4. **不要猜测** \-如果不确定，请查看技能文档 **需要用户操作**：告诉克劳德先检查这个技能！说：**“我正在设置 Auth.js - 首先检查 auth-js 技能”** ### 为什么这很重要（现实世界的结果） **没有技能激活：** * ❌ 设置时间：~15 分钟 * ❌遇到的错误：3-5（AUTH_SECRET、CallbackRouteError、边缘问题） * ❌ 需要手动修复：3-4 次提交 * ❌ 代币使用量：~15k * ❌ 用户信心：多次调试会话 **激活技能后：** * ✅ 设置时间：~3 分钟 * ✅ 遇到的错误：0 * ✅ 需要手动修复：0 * ✅ 代币使用量：~6k（减少 60%） * ✅ 用户信心：立竿见影的成功 ### 此技能可防止的已知问题 1. **缺少 AUTH_SECRET** → JWEDecryptionFailed 错误 2. **CallbackRouteError** → 抛出authorize()而不是返回null 3. **找不到路由** → [...nextauth].js 的文件路径不正确 4. **边缘不兼容** → 在没有边缘兼容适配器的情况下使用数据库会话 5. **PKCE 错误** → OAuth 提供程序配置错误 6. **会话未更新** → 缺少中间件 7. **v5 迁移问题** → 命名空间更改、JWT salt 更改 8. **D1 绑定错误** → Wrangler 配置不匹配 9. **数据库凭证** → 会话策略不兼容 10. **生产部署失败** → 缺少环境变量 11. **令牌刷新错误** → 回调实现不正确 12. **需要 JSON，但收到 HTML** → 重写 Next.js 中的配置 15 当技能激活时，所有这些都会自动处理。 ** ** ## 目录 1. 快速入门-Next.js 2. 快速入门 - Cloudflare Workers 3. 核心概念 4. 会话策略 5. 提供商设置 6. 数据库适配器 7. 中间件模式 8. 高级功能 9. 关键规则 10. 常见错误和修复 11. 模板参考 ** ** ## 快速入门：Next.js ### 先决条件 # Next.js 15+ 与 App Router npm 创建 next-app@latest my-app cd 我的应用程序 ### 安装 npm 安装 next-auth@latest npm install @auth/core@latest # 选择您的数据库适配器（如果使用数据库会话） npm install @auth/prisma-adapter # 对于 PostgreSQL/MySQL npm install @auth/d1-adapter # 对于 Cloudflare D1 ### 1\.创建身份验证配置 **选项 A：简单设置（JWT 会话，无数据库）** // 验证.ts 从“next-auth”导入 NextAuth 从“next-auth/providers/github”导入 GitHub 导出 const { 处理程序、 auth、登录、退出 } = NextAuth({ 提供者：[ GitHub({ clientId: process.env.AUTH_GITHUB_ID, clientSecret：process.env.AUTH_GITHUB_SECRET， }), ], }) **选项 B：边缘兼容设置（推荐用于中间件）** // auth.config.ts（边缘兼容，无数据库）从“next-auth”导入类型 { NextAuthConfig } 从“next-auth/providers/github”导入 GitHub 导出默认值{ 提供者：[ GitHub({ clientId: process.env.AUTH_GITHUB_ID, clientSecret：process.env.AUTH_GITHUB_SECRET， }), ], } 满足 NextAuthConfig // auth.ts（带有数据库的完整配置）从“next-auth”导入 NextAuth 从“@auth/prisma-adapter”导入 { PrismaAdapter } 从“@prisma/client”导入 { PrismaClient } 从“./auth.config”导入 authConfig const prisma = new PrismaClient() 导出 const { 处理程序、 auth、登录、退出 } = NextAuth({ 适配器：PrismaAdapter(prisma)， session: { Strategy: "jwt" }, // 关键：强制 JWT 实现边缘兼容性 ...authConfig， }) ### 2\.创建 API 路由处理程序 // 应用程序/api/auth/[...nextauth]/route.ts 从“@/auth”导入{处理程序} 导出 const { GET, POST } = 处理程序 ### 3\.添加中间件（可选但推荐） // 中间件.ts 从“@/auth”导出{auth作为中间件} 导出常量配置= { 匹配器: ["/((?!api|_next/static|_next/image|favicon.ico).*)"], } ### 4\.环境变量 # .env.local AUTH_SECRET=your-secret-here # 生成方式：npx auth Secret AUTH_GITHUB_ID=your_github_client_id AUTH_GITHUB_SECRET=your_github_client_secret # 关键：在生产中，需要 AUTH_SECRET ### 5\.在组件中使用 **服务器组件（应用程序路由器）：** 从“@/auth”导入{auth} 导出默认异步函数 Dashboard() { const 会话 = 等待 auth() if (!session?.user) { 返回

未验证

} 返回

欢迎{session.user.name}

} **客户端组件：** “使用客户端” 从“next-auth/react”导入{useSession} 导出默认函数 ClientDashboard() { const { 数据：会话，状态 } = useSession() if (status === "loading") return

正在加载...

if (status === "unauthenticated") return

未验证

欢迎{会话？.用户？.名称}

} ### 6\.登录/退出从“@/auth”导入{signIn，signOut} 导出函数 SignIn() { 返回（ <表格动作={异步()=>{ “使用服务器” 等待登录（“github”） }} > ） } 导出函数 SignOut() { 返回（ <表格动作={异步()=>{ “使用服务器” 等待退出（） }} > ） } ** ** ## 快速入门：Cloudflare Workers ### 先决条件 npm create cloudflare@latest my-auth-worker cd my-auth-worker ### 安装 npm install @auth/core@latest npm install @auth/d1-adapter@latest npm 安装 hono ### 1\.使用 D1 配置 Wrangler // 牧马人.jsonc { “名称”：“我的授权工人”， "main": "src/index.ts", “兼容性日期”：“2025-10-26”， “d1_数据库”：[ { “绑定”：“数据库”， “数据库名称”：“auth_db”， "database_id": "您的数据库 ID" } ] } ### 2\.创建D1数据库 # 创建数据库 npx 牧马人 d1 创建 auth_db # 将database_id复制到wrangler.jsonc # 创建表 npx wrangler d1 执行 auth_db --file=./schema.sql **架构.sql：** -- 有关完整架构，请参阅 templates/cloudflare-workers/schema.sql 创建表用户（ id 文本主键，名称文本，电子邮件文本唯一不为空，电子邮件已验证 INTEGER, 图像文本）；创建表帐户（ id 文本主键，用户 ID 文本不为空，输入文本不为空，提供者文本不为空，提供者帐户 ID 文本不为空，刷新令牌文本，访问令牌文本， expires_at INTEGER, 令牌类型文本，范围文本， id_token 文本，会话状态文本，删除级联时外键（userId）引用用户（id）， UNIQUE（提供商，提供商帐户 ID））；创建表会话（ id 文本主键，用户 ID 文本不为空，过期 INTEGER NOT NULL, sessionToken TEXT 唯一非空，删除级联时外键（userId）引用用户（id））；创建表验证令牌（标识符文本不为空，令牌文本唯一不为空，过期 INTEGER NOT NULL, 主键（标识符、令牌））； ### 3\.使用 Auth 创建 Worker // src/index.ts 从 'hono' 导入 { Hono } 从“@auth/core”导入{Auth} 从 '@auth/d1-adapter' 导入 { D1Adapter } 从 '@auth/core/providers/github' 导入 GitHub 类型绑定 = { 数据库：D1数据库 AUTH_SECRET：字符串 AUTH_GITHUB_ID：字符串 AUTH_GITHUB_SECRET：字符串 } const app = new Hono<{ 绑定: 绑定 }>() app.all('/api/auth/*', 异步 (c) => { const 响应 = 等待 Auth(c.req.raw, { 适配器：D1Adapter(c.env.DB), 提供者：[ GitHub({ clientId: c.env.AUTH_GITHUB_ID, clientSecret：c.env.AUTH_GITHUB_SECRET， }), ], 秘密：c.env.AUTH_SECRET，信任主机：真实， }) 返回响应 }) app.get('/', 异步 (c) => { // 示例：获取会话 const 会话 = 等待 Auth(c.req.raw, { 适配器：D1Adapter(c.env.DB), 提供者：[]，秘密：c.env.AUTH_SECRET， }) 返回 c.json({ 会话 }) }) 导出默认应用程序 ### 4\.环境变量 # 向 Cloudflare Workers 添加机密 npx 牧马人秘密放入 AUTH_SECRET npx 牧马人秘密放置 AUTH_GITHUB_ID npx 牧马人秘密放入 AUTH_GITHUB_SECRET ### 5\.部署 npx 牧马人部署 ** ** ## 核心概念 ### 会话策略 Auth.js v5 支持两种会话策略： 1. **JWT (JSON Web Token)** \- 未配置适配器时的默认值 * ✅ 在边缘运行时工作 * ✅ 会话没有数据库查询 * ✅ 快速且可扩展 * ❌ 无法使会话服务器端失效 * ❌ 代币大小限制 2. **数据库** \- 配置适配器时的默认值 * ✅ 完整的会话控制（无效、扩展） * ✅ 数据库中的审计跟踪 * ✅ 没有代币大小限制 * ❌ 每个请求都需要数据库查询 * ❌ 不兼容所有边缘运行时 **决策矩阵：** 使用案例|推荐策略|原因 ---|---|--- Next.js 应用路由器 |智威汤逊 |边缘运行时兼容性 Cloudflare 工人 | JWT 或数据库（带 D1）| D1 边缘兼容传统 Node.js |数据库|完整的会话控制高安全性|数据库|可以使会话无效只读会话 |智威汤逊 |无数据库开销详细比较请参见“references/session-strategies.md”。 ** ** ## 会话策略 ### JWT 会话（默认） **何时使用：** * 边缘运行时部署（Cloudflare Workers、Vercel Edge） * 没有配置数据库适配器 * 只读会话数据 * 高流量应用（无数据库查询） **配置：** 导出 const { 处理程序， auth } = NextAuth({ 会话：{ 策略：“jwt”， maxAge: 30 * 24 * 60 * 60, // 30 天 }, 提供者：[GitHub]， }) **⚠️ 关键：** 即使您配置了适配器，您也必须显式设置 `strategy: "jwt"` 以实现边缘运行时兼容性！ ### 数据库会话 **何时使用：** * Node.js 运行时（不是边缘） * 需要在服务器端使会话失效 * 合规性要求（审计跟踪） * 会话数据大于JWT限制 **配置：** 从“@auth/prisma-adapter”导入 { PrismaAdapter } 导出 const { 处理程序， auth } = NextAuth({ 适配器：PrismaAdapter(prisma)，会话：{ 策略：“数据库”，最大年龄：30 * 24 * 60 * 60， updateAge: 24 * 60 * 60, // 每24小时更新一次会话 }, 提供者：[GitHub]， }) **⚠️ Edge 运行时限制：** 如果您的适配器不兼容边缘，则无法在边缘运行时（中间件）中使用数据库会话。拆分您的配置： // auth.config.ts（边缘兼容）导出默认值{ 提供者：[GitHub]， } 满足 NextAuthConfig // auth.ts（带有数据库的完整配置）从“./auth.config”导入 authConfig 导出 const { 处理程序， auth } = NextAuth({ 适配器: PrismaAdapter(prisma), // 不边缘兼容 session: { Strategy: "jwt" }, // 强制中间件使用 JWT ...authConfig， }) ** ** ## 提供商设置 ### OAuth 提供商（GitHub、Google 等） **GitHub：** 从“next-auth/providers/github”导入 GitHub 导出 const { 处理程序， auth } = NextAuth({ 提供者：[ GitHub({ clientId: process.env.AUTH_GITHUB_ID, clientSecret：process.env.AUTH_GITHUB_SECRET， }), ], }) **Google（带有令牌刷新）：** 从“next-auth/providers/google”导入 Google 导出 const { 处理程序， auth } = NextAuth({ 提供者：[ 谷歌({ clientId：process.env.AUTH_GOOGLE_ID， clientSecret：process.env.AUTH_GOOGLE_SECRET，授权：{ 参数：{ 提示：“同意”， access_type: "离线", 响应类型：“代码”， }, }, }), ], }) 有关完整示例，请参阅“templates/providers/oauth-github-google.ts”。 ### 凭证提供者（电子邮件/密码） **⚠️ 重要：** 凭证提供程序仅支持 JWT 会话！从“next-auth/providers/credentials”导入凭证从“zod”导入{z} 从“bcryptjs”导入 bcrypt const signInSchema = z.object({ 电子邮件：z.string().email(), 密码：z.string().min(8), }) 导出 const { 处理程序， auth } = NextAuth({ 提供者：[ 凭证（{ 凭证：{ 电子邮件：{ 标签：“电子邮件”，类型：“电子邮件”}，密码：{ 标签：“密码”，类型：“密码”}， }, 授权：异步（凭据）=> { 尝试{ const { 电子邮件、密码 } = 等待 signInSchema.parseAsync(credentials) // 从数据库中获取用户 const user = wait db.user.findUnique({ 其中：{ email } }) if (!user || !user.password) { // 关键：返回 null，不要抛出异常返回空值 } const passwordMatch = wait bcrypt.compare(密码, user.password) 如果（！密码匹配）{ 返回空值 } // 返回用户对象返回{ id: 用户.id, 电子邮件：用户.电子邮件，名称：用户名， } } 捕获（错误）{ // 关键：出错时返回 null，不要抛出异常 console.error("验证错误：", error) 返回空值 } }, }), ], }) **⚠️关键规则：** 1. **永远不要在`authorize()`中抛出错误** - 总是返回`null` 2. **为什么？** 抛出错误会导致`CallbackRouteError`而不是`CredentialsSignin` 3. **在检查凭据之前始终使用 Zod 进行验证** 4. **使用 bcrypt 对密码进行哈希处理**，从不存储纯文本有关完整示例，请参阅“templates/providers/credentials.ts”。 ### Magic Link 提供商（无密码） **⚠️ 重要：** 魔法链接需要数据库适配器！从“next-auth/providers/resend”导入重新发送从“@auth/prisma-adapter”导入 { PrismaAdapter } 导出 const { 处理程序， auth } = NextAuth({ 适配器：PrismaAdapter(prisma), // 必需提供者：[ 重新发送({ apiKey: process.env.AUTH_RESEND_KEY, 来自：“noreply@example.com”， }), ], }) 有关完整示例，请参阅“templates/providers/magic-link-resend.ts”。 ** ** ## 数据库适配器 ### Cloudflare D1 适配器 **安装：** npm install @auth/d1-adapter@latest **牧马人配置：** // 牧马人.jsonc { “d1_数据库”：[ { “绑定”：“数据库”， “数据库名称”：“auth_db”， "database_id": "您的数据库 ID" } ] } **用途：** 从“@auth/d1-adapter”导入{D1Adapter} // Cloudflare 工作人员 const app = new Hono<{ 绑定: { DB: D1Database } }>() app.all('/api/auth/*', 异步 (c) => { 返回等待Auth（c.req.raw，{ 适配器：D1Adapter(c.env.DB), 提供者：[GitHub]， }) }) // Next.js（通过 wrangler 使用 D1）导出 const { 处理程序， auth } = NextAuth({ 适配器：D1Adapter(env.DB), session: { Strategy: "jwt" }, // 推荐用于边缘提供者：[GitHub]， }) **数据库架构：** 有关完整架构，请参阅“templates/cloudflare-workers/schema.sql”。 **边缘兼容性：** ✅ D1 完全边缘兼容！ ### Prisma 适配器 (PostgreSQL/MySQL) **安装：** npm install @auth/prisma-adapter@latest npm install @prisma/client@latest npm install -D prisma@latest **Prisma 架构：** // 棱镜/schema.prisma 生成器客户端{ 提供者=“prisma-client-js” } 数据源数据库{ 提供者=“postgresql” url = env("DATABASE_URL") } 模型用户{ id 字符串 @id @default(cuid()) 名称字符串？电子邮件字符串@unique 电子邮件验证日期时间？图像字符串？账户账户[] 会话会话[] } 模型帐户 { id 字符串 @id @default(cuid()) 用户 ID 字符串类型字符串提供者字符串提供者帐户 ID 字符串刷新令牌字符串？ @db.Text access_token 字符串？ @db.Text expires_at Int? token_type 字符串？范围字符串？ id_token 字符串？ @db.Text 会话状态字符串？ user 用户@relation（字段：[userId]，引用：[id]，onDelete：级联） @@unique([提供者, 提供者AccountId]) } 模型会话{ id 字符串 @id @default(cuid()) sessionToken 字符串 @unique 用户 ID 字符串过期日期时间 user 用户@relation（字段：[userId]，引用：[id]，onDelete：级联） } 模型 VerificationToken { 标识符字符串令牌字符串@unique 过期日期时间 @@unique([标识符, 标记]) } **用途：** 从“@auth/prisma-adapter”导入 { PrismaAdapter } 从“@prisma/client”导入 { PrismaClient } const prisma = new PrismaClient() 导出 const { 处理程序， auth } = NextAuth({ 适配器：PrismaAdapter(prisma)， session: { Strategy: "jwt" }, // 为了边缘兼容性提供者：[GitHub]， }) **边缘兼容性：** ❌ Prisma 默认情况下不边缘兼容 **解决方法：** 使用 Prisma Accelerate 或 Hyperdrive 实现边缘兼容性，或者强制 JWT 会话并且不在中间件中使用适配器。有关完整示例，请参阅“templates/database-adapters/prisma-postgresql.ts”。 ** ** ## 中间件模式 ### 会话保持活动状态 // 中间件.ts 从“@/auth”导出{auth作为中间件} 导出常量配置= { 匹配器: ["/((?!api|_next/static|_next/image|favicon.ico).*)"], } 这会自动更新每个请求的会话过期时间。 ### 路由保护 // 中间件.ts 从“@/auth”导入{auth} 从“next/server”导入 { NextResponse } 导出默认身份验证((req) => { const { 路径名 } = req.nextUrl // 保护/仪表板路由 if (pathname.startsWith("/dashboard")) { 如果（！req.auth）{ const loginUrl = new URL("/login", req.url) loginUrl.searchParams.set("callbackUrl", 路径名) 返回 NextResponse.redirect(loginUrl) } } 返回 NextResponse.next() }) 导出常量配置= { 匹配器: ["/((?!api|_next/static|_next/image|favicon.ico).*)"], } ### 基于角色的访问控制 (RBAC) // 验证.ts 导出 const { 处理程序， auth } = NextAuth({ 提供者：[GitHub]，回调：{ 异步 jwt({ 令牌, 用户 }) { // 登录时将角色添加到 JWT 如果（用户）{ 令牌.角色 = 用户.角色 } 返回令牌 }, 异步会话（{会话，令牌}）{ // 向会话公开角色 if (session.user) { 会话.用户.角色 = 令牌.角色 } 返回会话 }, }, }) // 中间件.ts 从“@/auth”导入{auth} 从“next/server”导入 { NextResponse } 导出默认身份验证((req) => { const { 路径名 } = req.nextUrl // 保护 /admin 路由（需要管理员角色） if (路径名.startsWith("/admin")) { if (!req.auth || req.auth.user.role !== "admin") { return NextResponse.redirect(new URL("/unauthorized", req.url)) } } 返回 NextResponse.next() }) 有关完整示例，请参阅“references/middleware-patterns.md”和“templates/advanced/role-based-access.ts”。 ** ** ## 高级功能 ### JWT 回调（自定义声明）导出 const { 处理程序， auth } = NextAuth({ 提供者：[GitHub]，回调：{ 异步 jwt({ 令牌、用户、帐户 }) { // 登录时如果（用户）{ 令牌.id = 用户.id 令牌.角色 = 用户.角色 } // 在后续请求中返回令牌 }, 异步会话（{会话，令牌}）{ // 向会话公开自定义声明会话.用户.id = 令牌.id 会话.用户.角色 = 令牌.角色返回会话 }, }, }) ### 令牌刷新 (OAuth) **带有令牌刷新的 Google OAuth：** 从“next-auth/providers/google”导入 Google 导出 const { 处理程序， auth } = NextAuth({ 提供者：[ 谷歌({ 授权：{ 参数：{ 提示：“同意”， access_type: "离线", 响应类型：“代码”， }, }, }), ], 回调：{ 异步 jwt({ 令牌, 帐户 }) { // 首次登录，保存token 如果（帐户）{ 返回{ ...令牌， access_token：帐户.access_token，过期时间：account.expires_at，刷新令牌：帐户.刷新令牌， } } // 后续登录，检查token是否过期 if (Date.now() < token.expires_at * 1000) { 返回令牌 } // Token过期，刷新尝试{ const 响应 = 等待 fetch("https://oauth2.googleapis.com/token", { 方法：“POST”，正文：新的 URLSearchParams({ client_id: process.env.AUTH_GOOGLE_ID!, client_secret: process.env.AUTH_GOOGLE_SECRET!, grant_type：“刷新令牌”，刷新令牌：令牌.刷新令牌！， }), }) const newTokens = 等待response.json() 返回{ ...令牌， access_token：newTokens.access_token， expires_at: Math.floor(Date.now() / 1000 + newTokens.expires_in), 刷新令牌：newTokens.refresh_token ?? token.refresh_token, } } 捕获（错误）{ console.error("令牌刷新错误：", error) token.error = "刷新令牌错误" 返回令牌 } }, 异步会话（{会话，令牌}）{ 会话.错误 = 令牌.错误返回会话 }, }, }) 有关完整示例，请参阅“templates/advanced/jwt-refresh-tokens.ts”。 ** ** ## 关键规则 ### ✅ 始终这样做： 1. **在生产中设置 AUTH_SECRET** # 生成秘密 npx 身份验证秘密 # 添加到.env.local AUTH_SECRET=您生成的秘密 2. **在 Credentialsauthorize() 中返回`null`（而不是抛出）** 授权：异步（凭据）=> { 如果（！有效用户）{ 返回 null // ✅ 正确 // throw new Error("Invalid") // ❌ 错误 - 导致 CallbackRouteError } } 3. **使用 Magic Links 适配器** 导出 const { 处理程序， auth } = NextAuth({ 适配器：PrismaAdapter(prisma), // 魔术链接所需提供者：[重新发送]， }) 4. **分割配置以实现边缘兼容性** // auth.config.ts（边缘兼容）导出默认值 {providers: [GitHub] } // auth.ts（带有数据库的完整配置）导出 const { 处理程序， auth } = NextAuth({ 适配器：PrismaAdapter(prisma)， session: { Strategy: "jwt" }, // 为边缘强制使用 JWT ...authConfig， }) 5. **使用非边缘适配器时强制 JWT 会话** 导出 const { 处理程序， auth } = NextAuth({ 适配器: PrismaAdapter(prisma), // 不边缘兼容会话：{策略：“jwt”}，//关键 }) ### ❌ 切勿这样做： 1. **不使用 AUTH_SECRET 进行部署** // 错误 - 将在生产中失败 // 缺少 AUTH_SECRET 环境变量 2. **在authorize()中抛出错误** 授权：异步（凭据）=> { throw new Error("无效凭据") // ❌ 导致 CallbackRouteError } 3. __使用已弃用的@next-auth/_适配器_* npm install @next-auth/prisma-adapter # ❌ 已弃用 npm install @auth/prisma-adapter # ✅ 正确 (v5) 4. **在中间件中使用没有边缘兼容适配器的数据库会话** // 错误 - Prisma 不边缘兼容导出 const { 处理程序， auth } = NextAuth({ 适配器：PrismaAdapter(prisma)， session: { Strategy: "database" }, // ❌ 中间件失败 }) 5. **混合 v4 和 v5 软件包** npm install next-auth@4.x @auth/core@0.x # ❌ 版本不匹配 ** ** ## 常见错误和修复 ### 1\.缺少 AUTH_SECRET **错误：** JWEDecryptionFailed：秘密无效 **原因：** `AUTH_SECRET` 环境变量丢失或不正确 **修复：** # 生成秘密 npx 身份验证秘密 # 添加到.env.local AUTH_SECRET=您生成的秘密 # 生产中（Vercel、Cloudflare 等） # 在仪表板中添加 AUTH_SECRET 作为环境变量 ### 2\.回调路由错误 **错误：** CallbackRouteError：非法参数：字符串，未定义 **原因：** 在 `authorize()` 回调中抛出错误 **修复：** // 错误授权：异步（凭据）=> { if (!user) 抛出新错误（“无效凭据”） } // 正确授权：异步（凭据）=> { if (!user) 返回 null 返回用户 } ### 3\.未找到路线 **错误：** 错误：未找到下一个身份验证路由 **原因：** API 路由处理程序的文件路径不正确 **修复：** // 确保文件位于确切路径： // 应用程序/api/auth/[...nextauth]/route.ts 从“@/auth”导入{处理程序} 导出 const { GET, POST } = 处理程序 ### 4\.边缘兼容性错误 **错误：** 模块与边缘运行时不兼容 **原因：** 将非边缘适配器与数据库会话策略结合使用 **修复：** // 选项 1：强制 JWT 会话导出 const { 处理程序， auth } = NextAuth({ 适配器：PrismaAdapter(prisma)，会话：{策略：“jwt”}，//✅ }) // 选项 2：使用边缘兼容适配器 (D1) 导出 const { 处理程序， auth } = NextAuth({ 适配器: D1Adapter(env.DB), // ✅ 边缘兼容会话：{策略：“数据库”}， }) ### 5\.会话未更新 **错误：** 会话过期但不刷新 **原因：** 缺少中间件 **修复：** // 中间件.ts 从“@/auth”导出{auth作为中间件} 导出常量配置= { 匹配器: ["/((?!api|_next/static|_next/image|favicon.ico).*)"], } ### 6-12。更多错误请参阅“references/common-errors.md”以获取所有 12 个已记录错误的完整列表并进行修复。 ** ** ## 模板参考所有模板都可以在“templates/”目录中找到： ### Next.js 模板 (5) * **auth.ts** \- 简单的 Next.js 配置（JWT 会话） * **auth.config.ts + auth.ts** \- 分割配置（边缘兼容） * **multi-provider.ts** \- OAuth + 凭证 + Magic Links * **middleware.ts** \- 会话保活+路由保护 * **package.json + .env.example** \- 依赖项 + 环境 ### Cloudflare Workers 模板 (3) * **worker-hono-auth.ts** \- 完整的 Hono + Auth.js + D1 * **wrangler.jsonc** \- D1 绑定配置 * **schema.sql** \- Auth.js 的 D1 表 ### 提供商模板 (3) * **oauth-github-google.ts** \- OAuth 设置 * **credentials.ts** \- 带有 Zod 验证的电子邮件/密码 * **magic-link-resend.ts** \- 无密码电子邮件身份验证 ### 高级模板（2） * **jwt-refresh-tokens.ts** \- Google 令牌轮换示例 * **基于角色的访问.ts** \- 具有自定义声明的 RBAC 将这些文件复制到您的项目并根据需要进行自定义。 ** ** ## 包版本 **当前（截至2025年10月26日）：** { “下一个验证”：“4.24.11”， “@auth/core”：“0.41.1”， "@auth/d1-适配器": "1.11.1", "@auth/prisma-adapter": "2.7.5", “下一个”：“15.3.1”， “荣誉”：“4.7.9” } **始终使用最新版本：** npm install next-auth@latest @auth/core@latest ** ** ## 官方文档 * **Auth.js 文档**： * **入门** : * **提供商**： * **适配器** : * **D1 适配器** : * **v5 迁移** : * **边缘兼容性**： ** ** ## 参考文档如需更深入的了解，请参阅： * **common-errors.md** \- 所有 12 个记录的错误和修复 * **edge-compatibility.md** \- 边缘运行时兼容性矩阵 * **v5-migration-guide.md** \- v4 → v5 重大更改 * **session-strategies.md** \- JWT 与数据库比较 * **middleware-patterns.md** \- 路由保护、RBAC * **jwt-customization.md** \- 自定义声明、令牌刷新 * **provider-setup-guides.md** \- OAuth 应用程序设置说明 ** ** **有问题吗？有问题吗？** 1. 首先检查 `references/common-errors.md` 2. 验证 AUTH_SECRET 是否已设置 3.确保你没有抛出authorize() 4. 检查适配器的边缘兼容性 5.查看官方文档：

授权Js

包含技能