编辑“︁Next.js中间件认证”︁（章节）

= Next.js中间件认证 =

== 介绍 ==  
'''Next.js中间件认证'''是Next.js框架中用于处理身份验证和授权的核心机制之一。中间件允许开发者在请求到达页面或API路由之前执行逻辑，例如验证用户权限、检查会话状态或重定向未授权用户。这种方法避免了在每个页面或API端点重复编写相同的认证代码，提高了代码的可维护性和安全性。

在Next.js中，中间件通过`middleware.js`或`middleware.ts`文件定义，并默认应用于项目中的所有路由（除非配置了特定路径匹配规则）。中间件运行在Edge Runtime环境下，这意味着它可以在全球分布的边缘节点上快速执行。

== 工作原理 ==  
Next.js中间件认证的流程通常如下：  

<mermaid>
graph TD
    A[客户端请求] --> B{中间件拦截}
    B -->|已认证| C[访问目标页面/API]
    B -->|未认证| D[重定向到登录页/返回401]
</mermaid>

关键特性：  
* **路由拦截**：在渲染页面或执行API逻辑前验证请求  
* **会话管理**：读取或修改Cookies、Headers等  
* **动态响应**：返回重定向、自定义响应或修改请求头  

== 基础示例 ==  
以下是一个简单的中间件认证实现，检查是否存在有效的会话Cookie：

<syntaxhighlight lang="javascript">
// middleware.js
import { NextResponse } from 'next/server'
import { verifyToken } from './lib/auth'

export async function middleware(request) {
  const token = request.cookies.get('sessionToken')?.value
  
  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url))
  }

  try {
    await verifyToken(token) // 验证JWT或其他令牌
    return NextResponse.next()
  } catch (error) {
    return NextResponse.redirect(new URL('/auth-error', request.url))
  }
}

// 配置中间件生效路径（可选）
export const config = {
  matcher: ['/dashboard/:path*', '/api/protected/:path*']
}
</syntaxhighlight>

'''代码说明'''：  
1. 从请求中提取`sessionToken` Cookie  
2. 如果令牌不存在，重定向到登录页  
3. 验证令牌有效性，无效则跳转到错误页  
4. `config.matcher`指定中间件仅对`/dashboard`和`/api/protected`路径生效  

== 高级模式 ==  

=== 角色基础访问控制（RBAC） ===  
扩展中间件以实现基于用户角色的权限控制：

<syntaxhighlight lang="javascript">
// middleware.js
export async function middleware(request) {
  const role = request.cookies.get('userRole')?.value
  const pathname = request.nextUrl.pathname

  // 管理员路径检查
  if (pathname.startsWith('/admin') && role !== 'admin') {
    return NextResponse.json(
      { error: 'Forbidden' },
      { status: 403 }
    )
  }

  // 付费用户路径检查
  if (pathname.startsWith('/premium') && !['premium', 'admin'].includes(role)) {
    return NextResponse.redirect(new URL('/plans', request.url))
  }

  return NextResponse.next()
}
</syntaxhighlight>

=== 条件性Cookies设置 ===  
在认证过程中动态设置Cookies：

<syntaxhighlight lang="javascript">
export async function middleware(request) {
  const response = NextResponse.next()
  const user = await getUserFromRequest(request)

  if (user?.preferences?.locale) {
    response.cookies.set('user-locale', user.preferences.locale)
  }

  return response
}
</syntaxhighlight>

== 性能优化 ==  

=== 路径匹配策略 ===  
通过精确配置`matcher`减少不必要的中间件执行：

<syntaxhighlight lang="javascript">
export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico|login).*)'
  ]
}
</syntaxhighlight>

此配置排除静态资源、API路由和登录页，使用正则表达式语法：  
* <code>(?!...)</code> 表示否定前瞻  
* <code>|</code> 分隔多个排除模式  

=== Edge Runtime限制 ===  
注意中间件运行环境的限制：  
* 最大脚本大小：1MB  
* 执行超时：约30秒（因部署平台而异）  
* 不支持Node.js特定API（如文件系统操作）  

== 实际案例 ==  

=== 电商平台权限控制 ===  
场景：限制未验证用户访问结算页面，同时区分普通用户和管理员  

<syntaxhighlight lang="javascript">
export async function middleware(req) {
  const { pathname } = req.nextUrl
  const session = await getSession(req)

  // 结算流程保护
  if (pathname.startsWith('/checkout') && !session) {
    return NextResponse.redirect(
      new URL(`/login?redirect=${encodeURIComponent(pathname)}`, req.url)
    )
  }

  // 商品管理后台保护
  if (pathname.startsWith('/admin/products') && session?.role !== 'admin') {
    return NextResponse.rewrite(new URL('/404', req.url))
  }

  return NextResponse.next()
}
</syntaxhighlight>

=== 多租户SaaS应用 ===  
根据子域名动态加载租户配置：

<syntaxhighlight lang="javascript">
export function middleware(req) {
  const hostname = req.headers.get('host')
  const subdomain = hostname.split('.')[0]

  // 注入租户信息到请求头
  const headers = new Headers(req.headers)
  headers.set('x-tenant-id', subdomain)

  return NextResponse.next({
    request: { headers }
  })
}
</syntaxhighlight>

== 数学原理 ==  
中间件认证的决策过程可以形式化为：  

<math>
\begin{cases}
\text{AllowAccess} & \text{if } \exists t \in \text{Cookies} \land \text{Verify}(t) \\
\text{DenyAccess} & \text{otherwise}
\end{cases}
</math>

其中：  
* <math>t</math> 代表认证令牌  
* <math>\text{Verify}(t)</math> 是验证函数  

== 常见问题 ==  

'''Q: 中间件与API路由中的认证有何区别？'''  
A: 中间件认证在路由处理前统一执行，避免重复代码；API路由认证则更灵活但需每个端点单独处理。

'''Q: 如何测试中间件逻辑？'''  
A: 使用Next.js提供的测试工具模拟请求：  
<syntaxhighlight lang="javascript">
import { createMiddlewareRunner } from 'next-test-middleware'
import middleware from './middleware'

const runMiddleware = createMiddlewareRunner(middleware)

test('redirects unauthenticated users', async () => {
  const { response } = await runMiddleware(
    new Request('http://localhost/dashboard'),
    { cookies: {} }
  )
  expect(response.status).toBe(307)
  expect(response.headers.get('location')).toContain('/login')
})
</syntaxhighlight>

== 最佳实践 ==  
1. **最小权限原则**：默认拒绝，按需允许  
2. **安全Cookie设置**：启用`HttpOnly`、`Secure`和`SameSite`属性  
3. **错误处理**：避免泄露敏感信息（如详细的验证错误）  
4. **性能监控**：跟踪中间件执行时间（尤其涉及外部验证服务时）  

== 延伸阅读 ==  
* [[Next.js官方中间件文档]]  
* [[OWASP认证指南]]  
* [[JWT/RFC 7519]]标准

[[Category:后端框架]]
[[Category:Next.js]]
[[Category:Next.js身份验证与授权]]