边缘安全加速平台 EO 中间件

一、使用场景

通过中间件，你可以实现包括但不限于以下能力：

·请求改写与路由控制：根据路径、域名、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 函数的上下文对象，包含以下属性：

GeoProperties 具体属性如下：

基本用法如下：

四、重定向 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.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 CLI 工具调试中间件，实时查看日志输出，验证功能是否符合预期。

# 启动本地开发服务edgeone makers dev

启动成功后，在中间件代码中使用 console.log() 输出调试信息，日志将实时显示在终端中。