求助：NextAuth.js v5服务端AccessToken刷新的Race Condition问题

问题描述 #

在Next.js应用中使用NextAuth.js v5时，遇到AccessToken刷新的竞态条件问题：多个并发请求会同时触发令牌刷新逻辑，既降低了效率，也带来了后端处理并发refresh token请求的压力。

现有实现分析 #

你已经尝试通过async-mutex库控制刷新操作的并发，但仍需优化几个关键环节：

• 全局Mutex实例在服务器环境下的单例性（避免模块重载导致重复创建）
• JWT回调中的令牌有效性判断存在时间窗口漏洞
• 刷新后的令牌更新逻辑需要更严谨

优化后的解决方案 #

1. 确保Mutex在服务器环境下的单例性 #

Next.js的服务器模块可能因热重载或多实例启动重复创建Mutex，需通过全局对象保证单例：

"use server";

import { decodeJWT } from "@/src/lib/utils";
import { headers } from "next/headers";
import { Mutex } from "async-mutex";

// 利用globalThis确保Mutex全局唯一，避免开发环境热重载重复实例化
const refreshTokenMutex = (globalThis as any).refreshTokenMutex || new Mutex();
if (process.env.NODE_ENV !== "production") {
  (globalThis as any).refreshTokenMutex = refreshTokenMutex;
}

export async function refreshAccessToken(token: any) {
  return await refreshTokenMutex.runExclusive(async () => {
    // 二次检查令牌有效性：避免等待Mutex期间令牌已被其他请求刷新
    if (Date.now() < token.exp - 60_000) {
      return token;
    }

    try {
      const refreshResponse = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/auth/refresh`, {
        method: "POST",
        headers: await headers(),
        credentials: "include", // 确保携带存储refresh token的HTTP-only Cookie
      });

      if (!refreshResponse.ok) {
        throw new Error(`刷新API响应状态：${refreshResponse.status}`);
      }

      const result = await refreshResponse.json();
      const newAccessToken = result.data?.access;

      if (!newAccessToken) {
        throw new Error("刷新响应中未包含有效AccessToken");
      }

      return {
        ...token,
        accessToken: newAccessToken,
        exp: decodeJWT(newAccessToken).exp * 1000,
        error: undefined, // 清除之前的错误标记
      };
    } catch (error) {
      console.error("令牌刷新失败:", error);
      return {
        ...token,
        error: "RefreshTokenError",
      };
    }
  });
}

2. 优化JWT回调逻辑 #

在auth.config.ts的jwt回调中增加错误状态判断，避免刷新失败后重复触发刷新：

async jwt({ token, user }) {
  // 初始登录时初始化令牌数据
  if (user) {
    token.sub = user.id;
    token.name = user.firstname;
    token.role = user.role;
    token.accessToken = user.accessToken;
    token.exp = decodeJWT(user.accessToken).exp * 1000;
    return token;
  }

  // 若已有刷新错误，直接返回避免重复触发
  if (token.error === "RefreshTokenError") {
    return token;
  }

  // 令牌仍在有效期内，直接返回
  if (token.accessToken && Date.now() < token.exp - 60_000) {
    return token;
  }

  // 触发令牌刷新
  return await refreshAccessToken(token);
}

3. 后端层面的额外防护（可选） #

为彻底解决并发刷新问题，后端可做以下优化：

• 对同一个refresh token的请求做幂等处理，标记正在处理中的请求
• 采用一次性refresh token机制，刷新成功后立即失效旧的refresh token
• 缓存已刷新的AccessToken，返回给后续相同refresh token的请求

关键注意事项 #

• 时间窗口防护：在Mutex内部二次校验令牌有效性，避免等待期间令牌已被刷新
• 单例Mutex：开发环境下通过globalThis保证Mutex不会重复创建
• 错误状态处理：刷新失败后标记错误，避免无限循环触发刷新

内容的提问来源于stack exchange，提问作者Naroto-Hasaka