Next.js 14 + next-auth@5中间件未触发问题求助

• 确认middleware.ts的位置与导出规范
  必须将middleware.ts放在项目根目录（与app/文件夹同级），且要默认导出middleware函数，同时导出config匹配规则。错误的位置或导出方式会直接导致中间件不注册：

  import { auth } from "@/auth";
  export default auth((req) => {
    console.log("Middleware triggered:", req.nextUrl.pathname);
  });
  
  export const config = {
    matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
  };
  

  注意：config是必填项，matcher要覆盖你需要拦截的路径，避免排除所有目标页面。

• 验证auth.ts的核心导出
  next-auth@5要求在auth.ts中导出auth、handlers等核心实例，同时确保credentials验证逻辑正确替换email为username：

  import NextAuth from "next-auth";
  import authConfig from "./auth.config";
  import Credentials from "next-auth/providers/credentials";
  
  export const { auth, handlers, signIn, signOut } = NextAuth({
    ...authConfig,
    providers: [
      Credentials({
        credentials: {
          username: { label: "Username", type: "text" },
          password: { label: "Password", type: "password" },
        },
        async authorize(credentials) {
          // 用username查询数据库，替换原email逻辑
          const user = await db.user.findUnique({
            where: { username: credentials?.username },
          });
          if (!user) return null;
          // 密码校验逻辑
          return user;
        },
      }),
    ],
  });
  

  缺失handlers或auth导出会导致中间件无法关联认证系统。

• 检查auth.config.ts的session回调配置
  替换email为username后，需在jwt和session回调中正确传递username字段，否则可能导致auth实例初始化异常：

  import type { AuthConfig } from "next-auth";
  
  export default {
    session: { strategy: "jwt" },
    callbacks: {
      async jwt({ token, user }) {
        if (user) token.username = user.username;
        return token;
      },
      async session({ session, token }) {
        if (session.user) session.user.username = token.username;
        return session;
      },
    },
  } satisfies AuthConfig;
  

• 排查版本兼容性
  确保next（13.5+）与next-auth@5版本匹配，建议使用next-auth@5的最新稳定版，版本不兼容可能导致中间件注册失败。

• 清除开发缓存
  Next.js开发服务器的缓存可能导致配置不生效，尝试：

  • 停止服务器，删除.next和node_modules/.cache文件夹
  • 重新启动开发服务
  • 用浏览器隐私模式测试，避免客户端缓存干扰

• 简化matcher规则测试
  如果当前matcher规则过于严格，可先简化为特定路径（如["/dashboard"]）测试，确认中间件是否能触发，逐步排查规则问题。

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