如何在Next.js中间件中识别预取请求以控制自定义逻辑执行时机

Next.js的预取请求（如next/link自动预取、router.prefetch()手动预取）会携带特定请求头，我们可以通过这些头精准区分预取请求和用户主动导航请求，确保自定义逻辑只在真实导航时运行。

核心判断逻辑 #

预取请求通常会携带以下两个特征头，组合判断可提高准确性：

• x-nextjs-prefetch: Next.js官方标记预取请求的专属头，值为1
• purpose: 部分浏览器/场景下的标准预取头，值为prefetch

完整中间件代码示例 #

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // 判断是否为预取请求
  const isPrefetch = 
    request.headers.get('x-nextjs-prefetch') === '1' || 
    request.headers.get('purpose') === 'prefetch';

  // 仅在非预取请求时执行自定义逻辑
  if (!isPrefetch) {
    // 这里替换成你的业务逻辑：比如用户导航统计、权限校验、自定义响应头设置等
    console.log('用户触发页面导航');
    
    const response = NextResponse.next();
    // 示例：添加导航标记头
    response.headers.set('x-user-navigated', 'true');
    return response;
  }

  // 预取请求直接放行，不执行自定义逻辑
  return NextResponse.next();
}

// 配置中间件生效范围：排除API、静态资源等非页面路径
export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

注意事项 #

• x-nextjs-prefetch是最可靠的判断依据，优先使用，purpose作为补充兼容特殊场景
• 通过config.matcher过滤掉API路由、静态文件等非页面导航请求，避免无效逻辑执行
• 该方案同时适用于Next.js 13+的App Router和Pages Router

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