中间件
概述
中间件允许您在页面加载之前拦截用户请求，并在 EdgeOne 的边缘节点上执行自定义逻辑，对请求进行实时处理后再继续转发或直接返回结果。借助边缘计算能力，中间件可以在离用户更近的位置完成判断与处理，从而降低回源与计算开销，提升访问性能与稳定性。
核心能力
中间件目前支持以下四种请求处理方式：
重定向 URL：返回 307/308 等状态码，将用户引导至新地址。
重写 URL：修改请求的目标路径，用户无感知。
修改请求头：添加或修改转发给源站的 HTTP Header。
直接返回响应：不访问源站，通过
new Response() 直接返回自定义内容。使用场景
通过中间件，您可以实现包括但不限于以下能力：
请求改写与路由控制：根据路径、域名、Header、Cookie、查询参数等条件重写 URL 或跳转到不同页面。
访问控制：基于请求信息进行 Token 鉴权校验、IP 限制、Referer 防盗链等访问拦截。
灰度发布与 A/B 测试：按用户标识、Cookie、UA 等特征将请求分流至不同版本，实现灰度发布或定向内容投放。
直接返回结果：对特定请求直接返回自定义内容（如 301/302 跳转、JSON 响应、HTML 页面），无需访问源站。
注意：
中间件适用于轻量级、低延迟的请求逻辑处理场景；复杂计算或长耗时任务建议放在后端服务中执行。
快速开始
1. 创建中间件文件
在项目根目录下创建
middleware.js （或 middleware.ts）文件，导出函数middleware，参考下面的示例代码：// middleware.jsexport function middleware(context) {const { request, next, redirect, rewrite } = context;// 请求直接透传return next();}
2. Context 对象
context 是传递给 middleware 函数的上下文对象，包含以下属性：属性 | 类型 | 描述 |
request | Request | 当前请求的 Request 对象 |
next | (options?: { headers?: Record<string, any> }) => Response | 继续处理请求，可传入参数修改请求头 |
redirect | (url: string, status?: number) => Response | 重定向，默认状态码 307 |
rewrite | (url: string) => Response | 重写请求路径 |
基本用法如下：
重定向 URL
export function middleware(context) {const { request, redirect } = context;const url = new URL(request.url);// 重定向if (url.pathname === '/protected') {return redirect('/login'， 308);}}
重写 URL
export function middleware(context) {const { request, rewrite } = context;const url = new URL(request.url);// 重写if (url.pathname === '/old-path') {return rewrite('/new-path'); // 相对路径// return rewrite('https://www.google.com'); // 绝对路径}}
修改请求头
export function middleware(context) {// 修改转发给源站的请求 headerreturn context.next({headers: {'x-custom-header': 'middleware-added','x-request-id': Math.random(),}});}
直接返回响应
export function middleware(context) {// 直接返回响应return new Response('Hello World');}
3. 路由匹配配置
中间件默认匹配所有路由。如果只需要在特定路径下触发中间件，可以导出
config 对象并配置 matcher 字段。// middleware.jsexport function middleware(context) {// 中间件逻辑return context.next();}// 配置路由匹配规则export const config = {matcher: ['/:path*', // 匹配所有路由],};
matcher 支持以下配置方式：单路径匹配
export const config = {matcher: '/about',};
多路径匹配
export const config = {matcher: ['/api/:path*', '/about/:path*'],};
正则表达式匹配
export const config = {matcher: ['/api/.*', '^/user/\d+$'],};
4. 本地开发调试
# 启动本地开发服务edgeone pages dev
启动成功后，在中间件代码中使用
console.log() 输出调试信息，日志将实时显示在终端中。
