边缘开发者平台
  • Pages
    • 产品简介
    • 快速开始
      • 导入 Git 仓库
      • 从模板开始
      • 直接上传
      • 从 AI 开始
    • 框架指南
      • 前端
        • Vite
        • React
        • Vue
        • 其他框架
      • 后端
      • 全栈
        • Next.js
        • Nuxt
        • Astro
        • React Router
        • SvelteKit
        • TanStack Start
        • Vike
      • 自定义 404 页面
    • 项目指南
      • 项目管理
      • edgeone.json
      • 缓存配置
      • 错误码
    • 构建指南
    • 部署指南
      • 概览
      • 触发部署
      • 管理部署
      • 部署按钮
      • 使用 Github Action
      • 使用 CNB 插件
      • 使用 IDE 插件
      • 使用 CodeBuddy IDE
    • 域名管理
      • 概览
      • 自定义域名
      • 配置 HTTPS 证书
        • 概览
        • 申请免费证书
        • 使用 SSL 托管证书
      • 配置 DNS 的 CNAME 记录
    • 可观测性
      • 概览
      • 指标分析
      • 日志分析
    • Pages Functions
      • 概览
      • Edge Functions
      • Cloud Functions
        • 概览
        • Node Functions
    • 中间件
    • KV 存储
    • 边缘 AI
    • API Token
    • EdgeOne CLI
    • Pages MCP
    • 消息通知
    • 集成指南
      • AI
        • 对话型大模型集成
        • 图片大模型集成
      • 数据库
        • Supabase 集成
        • Pages KV 集成
      • 电商
        • Shopify 集成
        • WooCommerce 集成
      • 支付
        • Stripe 集成
        • Paddle 集成
      • CMS
        • WordPress 集成
        • Contentful 集成
        • Sanity 集成
        • Payload 集成
      • 身份验证
        • Supabase 集成
        • Clerk 集成
    • 最佳实践
      • 使用通用大模型快速搭建 AI 应用
      • 使用边缘 AI 模型快速搭建对话型 AI 站点
      • 使用 Shopify 搭建电商平台
      • 使用 Supabase 和 Stripe 搭建 SaaS 站点
      • 如何快速搭建公司品牌站点
      • 如何快速搭建博客站点
    • 迁移指南
      • 从 Vercel 迁移至 EdgeOne Pages
      • 从 Cloudflare Pages 迁移至 EdgeOne Pages
      • 从 Netlify 迁移至 EdgeOne Pages
    • 排障指南
    • 常见问题
    • 联系我们
    • 产品动态
文档概览/
边缘开发者平台/
Pages/
中间件/

中间件

概述

中间件允许您在页面加载之前拦截用户请求，并在 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() 输出调试信息，日志将实时显示在终端中。