Next.js 中间件重定向循环修复：排查与配置实战

快速答案

• 核心结论：Next.js 中间件重定向循环通常由条件逻辑不完善（如未排除目标路径或静态资源）导致，修复关键在于使用 matcher 精确控制路径范围，并在重定向后设置标记（如 cookie）避免重复触发。
• 第一检查项：确认中间件中重定向的目标路径是否被 matcher 包含，以及是否排除了 _next/static、/api 等路径。
• 最小修复命令：在中间件中添加条件判断 if (request.cookies.has('redirected')) return NextResponse.next()，并在重定向时设置 cookie。
• 适用环境：Next.js 14 Pages Router，Edge Runtime；不适用于 App Router 的某些 API（如 NextRequest 差异）。
• 版本边界：Next.js 13.4+ 中间件 API 稳定，但 matcher 配置在 14.x 中要求静态字符串。

它解决什么问题 / 适用场景

Next.js 中间件允许在路由匹配前执行自定义逻辑，常用于认证校验、国际化重定向、A/B 测试等场景。但当重定向逻辑不完善时，容易陷入无限循环：例如，中间件将 /dashboard 重定向到 /login，而 /login 又因某种条件被重定向回 /dashboard。

该修复方案适用于：

• 使用 Next.js 14 Pages Router 的项目
• 中间件中使用了条件重定向（基于 cookie、认证状态或路径匹配）
• 需要精细控制请求预处理（如权限校验、A/B 测试、国际化重定向）的团队
• 与 Vercel 或 Node.js 服务器配合使用的场景

注意：若使用 App Router，需注意 NextRequest 和 NextResponse API 的差异（如 cookies 对象的用法不同）。

核心配置 / 参数说明

中间件基础结构

TYPESCRIPT
// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  // 防止重定向循环：检查是否已重定向过
  if (request.cookies.has('redirected')) {
    return NextResponse.next()
  }

  const { pathname } = request.nextUrl

  // 排除静态资源和 API 路由
  if (
    pathname.startsWith('/_next') ||
    pathname.startsWith('/api') ||
    pathname.startsWith('/static')
  ) {
    return NextResponse.next()
  }

  // 示例：未认证用户重定向到登录页
  if (pathname.startsWith('/dashboard') && !request.cookies.has('auth')) {
    const loginUrl = new URL('/login', request.url)
    const response = NextResponse.redirect(loginUrl)
    // 设置标记 cookie 防止循环
    response.cookies.set('redirected', 'true', { maxAge: 10 })
    return response
  }

  return NextResponse.next()
}

export const config = {
  matcher: [
    /*
     * 匹配所有路径，但排除：
     * - _next/static (静态资源)
     * - _next/image (图片优化)
     * - favicon.ico (网站图标)
     * - api (API 路由)
     */
    '/((?!_next/static|_next/image|favicon.ico|api).*)',
  ],
}

关键参数说明

matcher 路径匹配规则

与同类方案对比

选择建议：

• 静态重定向（如 /old-page → /new-page）：使用 next.config.js redirects
• 动态认证校验：使用中间件
• 页面级数据获取：使用 getServerSideProps
• 需要 WebSocket 或自定义路由：使用自定义服务器

在 AI 客户端中的集成配置

Claude Desktop / Cursor 配置

若需在 AI 开发工具中模拟中间件行为（如本地测试重定向逻辑），可使用以下 JSON 配置：

JSON
{
  "mcpServers": {
    "nextjs-middleware-fix": {
      "command": "node",
      "args": [
        "-e",
        "const { createServer } = require('http'); const { parse } = require('url'); const next = require('next'); const dev = process.env.NODE_ENV !== 'production'; const app = next({ dev }); const handle = app.getRequestHandler(); app.prepare().then(() => { createServer((req, res) => { const parsedUrl = parse(req.url, true); const { pathname } = parsedUrl; // 模拟中间件逻辑：防止重定向循环 if (pathname.startsWith('/dashboard') && req.headers.cookie?.includes('redirected=true')) { res.writeHead(302, { Location: '/home' }); res.end(); } else { handle(req, res, parsedUrl); } }).listen(3000, (err) => { if (err) throw err; console.log('> Ready on http://localhost:3000'); }); });"
      ]
    }
  }
}

注意：此配置仅用于本地开发测试，生产环境应使用 Next.js 内置中间件。

生产环境实践与注意事项

1. 性能优化

• 避免耗时操作：中间件在每个请求中执行，应避免数据库查询或外部 API 调用。若必须使用，建议使用 fetch 并设置超时。
• 使用 matcher 缩小范围：不要使用 matcher: ['/:path*']，应精确指定需要中间件的路径。
• 缓存策略：对于频繁检查的认证状态，考虑使用 cookie 或 JWT 而非每次查询数据库。

2. 安全性

• 防止开放重定向：验证重定向目标 URL 是否在允许的白名单内，避免用户被重定向到恶意站点。
• 避免暴露敏感信息：不要在中间件中输出 token 或密钥到响应头。
• cookie 安全：设置 httpOnly 和 secure 标记，避免 XSS 攻击。

3. 部署注意事项

• Edge Runtime 限制：中间件运行在 Edge Runtime，不支持 fs、path 等 Node.js 原生模块。如需使用，考虑迁移到 Node.js Runtime（Next.js 15+ 支持）。
• 执行顺序：中间件在 next.config.js redirects 之后执行，若两者冲突，redirects 优先。
• 监控与日志：在中间件中添加日志记录（如 console.log），但注意 Edge Runtime 的日志输出可能有限。

常见报错与排查

错误 1：重定向循环

报错信息：Error: Redirect loop detected - infinite redirects between /login and /dashboard

解决方案：

1. 检查中间件中的条件逻辑，确保重定向目标路径不在 matcher 范围内
2. 使用 cookie 标记已重定向的请求：

TYPESCRIPT
if (request.cookies.has('redirected')) {
  return NextResponse.next()
}
// 重定向时设置标记
response.cookies.set('redirected', 'true', { maxAge: 10 })

3. 排除静态资源路径：

TYPESCRIPT
matcher: ['/((?!_next/static|_next/image|favicon.ico|api).*)']

错误 2：matcher 配置错误

报错信息：Error: The 'matcher' value must be a constant string or array of strings

解决方案：

• 确保 matcher 是静态字符串或数组，不能使用变量：

TYPESCRIPT
// 正确
export const config = { matcher: ['/dashboard/:path*'] }

// 错误
const dynamicPath = '/dashboard/:path*'
export const config = { matcher: [dynamicPath] }

错误 3：中间件未在预期路径执行

报错信息：Error: Middleware is not running on expected paths

解决方案：

1. 检查 matcher 路径格式（必须以 / 开头）
2. 确认路径匹配规则（如 /about/:path 不匹配 /about/a/c）
3. 使用条件语句作为备选：

TYPESCRIPT
export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    // 自定义逻辑
  }
}

错误 4：请求头过大

报错信息：Error: 431 Request Header Fields Too Large

解决方案：

• 避免在中间件中设置过大的请求或响应头（如大型 cookie）
• 使用外部存储（如 Redis）传递数据，而非 header
• 限制 cookie 大小（建议 < 4KB）

常见问题 FAQ

Q: 如何在中间件中避免重定向循环？

A: 在中间件中添加条件检查，例如：如果请求已包含特定 cookie（如 redirected=true），则不再执行重定向。同时，使用 matcher 排除静态资源路径（如 _next/static）和 API 路由，确保重定向目标路径不在 matcher 范围内。示例代码见上方「核心配置」章节。

Q: 中间件和 next.config.js 中的 redirects 有什么区别？

A: next.config.js 的 redirects 是静态配置，在构建时确定，适合简单、固定的重定向规则（如永久重定向）。中间件则在运行时执行，支持动态逻辑（如基于 cookie、用户角色），但性能开销稍大。建议：静态规则用 redirects，动态规则用中间件。

Q: 中间件中可以使用外部 API 或数据库吗？

A: 可以，但需注意性能影响。中间件在 Edge Runtime 中运行，支持 fetch API 调用外部服务，但不支持 Node.js 原生模块。建议将耗时操作（如数据库查询）放在页面或 API 路由中，中间件仅做轻量级检查（如 token 验证）。若必须使用数据库，考虑使用 Redis 或边缘数据库（如 PlanetScale）。

官方参考

• Next.js 中间件官方文档