文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>边缘安全加速平台 EO>Pages>中间件

中间件

最近更新时间：2026-03-06 17:58:01

我的收藏

本页目录：

概述

中间件允许您在页面加载之前拦截用户请求，并在 EdgeOne 的边缘节点上执行自定义逻辑，对请求进行实时处理后再继续转发或直接返回结果。借助边缘计算能力，中间件可以在离用户更近的位置完成判断与处理，从而降低回源与计算开销，提升访问性能与稳定性。

使用场景

通过中间件，您可以实现包括但不限于以下能力：
请求改写与路由控制：根据路径、域名、Header、Cookie、查询参数等条件重写 URL 或跳转到不同页面。
访问控制：基于请求信息进行 Token 鉴权校验、IP / 地域限制、Referer 防盗链等访问拦截。
灰度发布与 A/B 测试：按用户标识、Cookie、地域、UA 等特征将请求分流至不同版本，实现灰度发布或定向内容投放。
直接返回结果：对特定请求直接返回自定义内容（例如 301/302 跳转、JSON 响应、HTML 页面），无需访问源站。
注意：
中间件适用于轻量级、低延迟的请求逻辑处理场景；复杂计算或长耗时任务建议放在后端服务中执行。

快速开始

1. 创建中间件文件

在项目根目录下创建 middleware.js （或 middleware.ts）文件，导出函数middleware，参考下面的示例代码：
// middleware.js
export 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
重写请求路径
geo
GeoProperties
客户端请求的位置信息
clientIp
string
客户端 IP 地址
GeoProperties 具体属性如下：
属性
类型
描述
示例值
asn
number
ASN
132203
countryName
string
国家名
Singapore
countryCodeAlpha2
string
国家的 ISO-3166 alpha2 代码
SG
countryCodeAlpha3
string
国家的 ISO-3166 alpha3 代码
SGP
countryCodeNumeric
string
国家的 ISO-3166 numeric 代码
702
regionName
string
区域名
-
regionCode
string
区域代码
AA-AA
cityName
string
城市名
Singapore
latitude
number
纬度
1.29027
longitude
number
经度
103.851959
基本用法如下：

重定向 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) {
    // 修改转发给源站的请求 header
    return 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.js
export 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 CLI 工具调试中间件，实时查看日志输出，验证功能是否符合预期。
# 启动本地开发服务
edgeone pages dev
启动成功后，在中间件代码中使用 console.log() 输出调试信息，日志将实时显示在终端中。

中国站
目录