Next-Auth v5（Beta）路由中Auth wrapper/session返回undefined，求角色权限方案

一、核心配置排查 #

req.auth或session返回undefined，优先检查基础配置：

• 确保auth.ts（或[...nextauth].ts）中配置了secret，且与.env文件的NEXTAUTH_SECRET完全一致（生产环境必须用openssl rand -hex 32生成安全密钥）
• App Router项目需在app/api/auth/[...nextauth]/route.ts正确导出Auth路由
• 跨域请求或Postman测试时，需手动携带Authorization: Bearer <token>请求头，或确保Cookie可正常传递（同域请求默认自动携带）

二、Next-Auth v5 路由保护实现 #

使用v5官方auth包装器的正确写法，自动处理认证校验：

import { auth } from "../../auth";

export const POST = auth(async (req) => {
  // 未认证直接拦截
  if (!req.auth) {
    return Response.json({ error: "未授权访问" }, { status: 401 });
  }

  // 角色权限校验
  if (!req.auth.user?.roles?.includes("admin")) {
    return Response.json({ error: "权限不足" }, { status: 403 });
  }

  // 执行业务逻辑
  return Response.json({ message: "操作成功", user: req.auth.user });
});

三、基于Session的权限控制（兼容v4及更早版本） #

通过getServerSession手动获取会话，需传入Auth配置项：

import { getServerSession } from "next-auth/next";
import { authOptions } from "../../auth/[...nextauth]";

export const POST = async (req) => {
  const session = await getServerSession(authOptions);
  
  if (!session) {
    return new Response(JSON.stringify({ error: "未授权" }), {
      status: 401,
      headers: { "Content-Type": "application/json" },
    });
  }

  // 角色校验逻辑
  if (session.user.role !== "editor") {
    return new Response(JSON.stringify({ error: "权限不足" }), {
      status: 403,
    });
  }

  // 业务处理
  return new Response(JSON.stringify({ data: "处理完成" }), { status: 200 });
};

四、基于JWT Token的权限控制 #

适合跨域或无Cookie场景，手动解析验证Token：

import jwt from "jsonwebtoken";
import { authOptions } from "../../auth/[...nextauth]";

export const POST = async (req) => {
  // 从请求头提取Token
  const authHeader = req.headers.get("authorization");
  const token = authHeader?.replace("Bearer ", "");

  if (!token) {
    return Response.json({ error: "缺少认证凭证" }, { status: 401 });
  }

  try {
    // 用Next-Auth密钥解析Token
    const decoded = jwt.verify(token, authOptions.secret);
    
    // 角色权限校验
    if (!decoded.roles?.includes("viewer")) {
      return Response.json({ error: "权限不足" }, { status: 403 });
    }

    return Response.json({ message: "操作成功", userInfo: decoded });
  } catch (err) {
    return Response.json({ error: "无效或过期的Token" }, { status: 401 });
  }
};

注：需先安装依赖包：npm install jsonwebtoken

五、额外排查点 #

• App Router项目中，API路由必须使用Response对象返回结果，不能用旧版res.send
• 生产环境必须设置NEXTAUTH_URL为你的正式域名
• 测试时确保用户处于登录状态，会话/Token未过期

内容的提问来源于stack exchange，提问作者Honey Patel