Clerk Auth获取用户列表异常：新用户偶尔无法返回

问题场景 #

我在Next.js应用中通过App Router创建了/users/route.ts API路由，使用Clerk客户端获取用户列表，但新注册用户偶尔无法被返回——Clerk控制台能看到所有用户，重启服务器也无法解决。代码如下：

export const GET = async (req: NextRequest) => {
  try {
    const { data: users } = await clerkClient.users.getUserList();
    return NextResponse.json(users);
  } catch (error) {
    return NextResponse.json({ error: 'Failed to fetch users' }, { status: 500 });
  }
};

解决方案 #

1. 禁用Next.js API路由的静态缓存 #

Next.js App Router的GET API路由默认会静态缓存响应，导致后续请求直接复用旧数据，不会重新调用Clerk接口获取最新用户。在路由文件顶部添加动态配置：

export const dynamic = 'force-dynamic'; // 强制每次请求都执行服务器端逻辑

export const GET = async (req: NextRequest) => {
  // 原有代码不变
};

或者在响应中直接设置缓存头：

export const GET = async (req: NextRequest) => {
  try {
    const { data: users } = await clerkClient.users.getUserList();
    return NextResponse.json(users, {
      headers: {
        'Cache-Control': 'no-store, max-age=0', // 完全禁用缓存
      },
    });
  } catch (error) {
    return NextResponse.json({ error: 'Failed to fetch users' }, { status: 500 });
  }
};

2. 跳过Clerk客户端的内置缓存 #

Clerk客户端默认会缓存用户数据，可通过skipCache参数强制拉取最新数据：

export const GET = async (req: NextRequest) => {
  try {
    const { data: users } = await clerkClient.users.getUserList({
      skipCache: true, // 跳过Clerk本地缓存
    });
    return NextResponse.json(users);
  } catch (error) {
    return NextResponse.json({ error: 'Failed to fetch users' }, { status: 500 });
  }
};

3. 处理分页获取所有用户 #

Clerk的getUserList默认最多返回100个用户，如果新用户超出默认分页范围，需要循环获取所有页的数据：

export const GET = async (req: NextRequest) => {
  try {
    let allUsers = [];
    let page = 1;
    const limit = 100; // Clerk允许的单页最大数量

    while (true) {
      const { data: users, totalCount } = await clerkClient.users.getUserList({
        limit,
        page,
        skipCache: true,
      });
      allUsers = [...allUsers, ...users];
      if (allUsers.length >= totalCount) break;
      page++;
    }

    return NextResponse.json(allUsers);
  } catch (error) {
    return NextResponse.json({ error: 'Failed to fetch users' }, { status: 500 });
  }
};

4. 更新Clerk依赖到最新版本 #

旧版本的Clerk SDK可能存在缓存或数据同步bug，执行命令更新依赖：

npm update @clerk/nextjs @clerk/clerk-sdk-node

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