edgeone-makers-middleware

中间件

在边缘（V8 运行时）运行的轻量级请求拦截。可用于重定向、重写、身份验证保护、A/B 测试和注入标头。

⚠️ 框架项目（Next.js、Nuxt 等）：请勿使用此平台的中间件格式。请改用框架内置的中间件（例如，Next.js middleware.ts 配合 NextRequest/NextResponse）。以下模式仅适用于非框架项目或纯静态项目。

基本中间件

文件：middleware.js（项目根目录）

export function middleware(context) {
  const { request, next, redirect, rewrite } = context;

  // Pass through — no modification
  return next();
}

上下文 API

属性	类型	描述
request	Request	当前请求对象
next(options?)	Function	继续访问源站；也可选择修改标头
redirect(url, status?)	Function	重定向（默认 307）
rewrite(url)	Function	重写请求路径（对客户端透明）
geo	GeoProperties	客户端地理位置
clientIp	string	客户端 IP 地址

路由匹配

默认情况下，中间件会在所有路由上运行。使用 config.matcher 限定范围：

// Only run on /api/* routes
export const config = {
  matcher: ['/api/:path*'],
};

export function middleware(context) {
  // Auth check for API routes only
  const token = context.request.headers.get('Authorization');
  if (!token) {
    return new Response('Unauthorized', { status: 401 });
  }
  return context.next();
}

匹配器模式：

// Single path
export const config = { matcher: '/about' };

// Multiple paths
export const config = { matcher: ['/api/:path*', '/admin/:path*'] };

// Regex
export const config = { matcher: ['/api/.*', '^/user/\\d+$'] };

常见模式

URL 重定向

export function middleware(context) {
  const url = new URL(context.request.url);

  if (url.pathname === '/old-page') {
    return context.redirect('/new-page', 301);
  }
  return context.next();
}

URL 重写（透明代理）

export function middleware(context) {
  const url = new URL(context.request.url);

  if (url.pathname.startsWith('/blog')) {
    return context.rewrite('/content' + url.pathname);
  }
  return context.next();
}

添加请求标头

export function middleware(context) {
  return context.next({
    headers: {
      'x-request-id': crypto.randomUUID(),
      'x-client-ip': context.clientIp,
      'x-country': context.geo.countryCodeAlpha2,
    },
  });
}

身份验证保护

export const config = {
  matcher: ['/api/:path*', '/admin/:path*'],
};

export function middleware(context) {
  const token = context.request.headers.get('Authorization');
  if (!token || !token.startsWith('Bearer ')) {
    return new Response(JSON.stringify({ error: 'Unauthorized' }), {
      status: 401,
      headers: { 'Content-Type': 'application/json' },
    });
  }
  return context.next();
}

基于地理位置的路由

export function middleware(context) {
  const country = context.geo.countryCodeAlpha2;

  if (country === 'CN') {
    return context.rewrite('/zh' + new URL(context.request.url).pathname);
  }
  return context.next();
}

A/B 测试

export function middleware(context) {
  const url = new URL(context.request.url);

  if (url.pathname === '/landing') {
    const variant = Math.random() < 0.5 ? '/landing-a' : '/landing-b';
    return context.rewrite(variant);
  }
  return context.next();
}

直接返回 JSON 响应

export function middleware(context) {
  const url = new URL(context.request.url);

  if (url.pathname === '/api/health') {
    return new Response(JSON.stringify({ status: 'ok', timestamp: Date.now() }), {
      headers: { 'Content-Type': 'application/json' },
    });
  }
  return context.next();
}

GeoProperties

可通过 context.geo 获取：

属性	类型	示例
countryName	string	新加坡
countryCodeAlpha2	string	SG
countryCodeAlpha3	string	SGP
regionName	string	—
cityName	string	新加坡
latitude	number	1.29027
longitude	number	103.851959
asn	number	132203