routing-middleware
GitHub指导Vercel路由中间件的使用，用于请求拦截、重写和重定向。支持Edge/Node/Bun运行时，适用于任意框架。明确区分路由中间件、Next.js 16代理及边缘函数，并提供Bun配置及基础示例。
触发场景
安装
npx skills add openai/plugins --skill routing-middleware -g -y
SKILL.md
Frontmatter
{
"name": "routing-middleware",
"metadata": {
"docs": [
"https:\/\/nextjs.org\/docs\/app\/building-your-application\/routing\/middleware",
"https:\/\/vercel.com\/docs\/routing-middleware"
],
"sitemap": "https:\/\/nextjs.org\/sitemap.xml",
"priority": 6,
"bashPatterns": [
"\\bnpx\\s+@vercel\/config\\b"
],
"pathPatterns": [
"middleware.ts",
"middleware.js",
"middleware.mts",
"middleware.mjs",
"proxy.ts",
"proxy.js",
"proxy.mts",
"proxy.mjs",
"src\/middleware.ts",
"src\/middleware.js",
"src\/middleware.mts",
"src\/middleware.mjs",
"src\/proxy.ts",
"src\/proxy.js",
"src\/proxy.mts",
"src\/proxy.mjs",
"vercel.json",
"apps\/*\/vercel.json",
"vercel.ts",
"vercel.mts"
]
},
"description": "Vercel Routing Middleware guidance — request interception before cache, rewrites, redirects, personalization. Works with any framework. Supports Edge, Node.js, and Bun runtimes. Use when intercepting requests at the platform level."
}
Vercel Routing Middleware
You are an expert in Vercel Routing Middleware — the platform-level request interception layer.
What It Is
Routing Middleware runs before the cache on every request matching its config. It is a Vercel platform feature (not framework-specific) that works with Next.js, SvelteKit, Astro, Nuxt, or any deployed framework. Built on Fluid Compute.
- File:
middleware.tsormiddleware.jsat the project root - Default export required (function name can be anything)
- Runtimes: Edge (default), Node.js (
runtime: 'nodejs'), Bun (Node.js +bunVersionin vercel.json)
CRITICAL: Middleware Disambiguation
There are THREE "middleware" concepts in the Vercel ecosystem:
| Concept | File | Runtime | Scope | When to Use |
|---|---|---|---|---|
| Vercel Routing Middleware | middleware.ts (root) |
Edge/Node/Bun | Any framework, platform-level | Request interception before cache: rewrites, redirects, geo, A/B |
| Next.js 16 Proxy | proxy.ts (root, or src/proxy.ts if using --src-dir) |
Node.js only | Next.js 16+ only | Network-boundary proxy needing full Node APIs. NOT for auth. |
| Edge Functions | Any function file | V8 isolates | General-purpose | Standalone edge compute endpoints, not an interception layer |
Why the rename in Next.js 16: middleware.ts → proxy.ts clarifies it sits at the network boundary (not general-purpose middleware). Partly motivated by CVE-2025-29927 (middleware auth bypass via x-middleware-subrequest header). The exported function must also be renamed from middleware to proxy. Migration codemod: npx @next/codemod@latest middleware-to-proxy
Deprecation: Next.js 16 still accepts middleware.ts but treats it as deprecated and logs a warning. It will be removed in a future version.
Bun Runtime
To run Routing Middleware (and all Vercel Functions) on Bun, add bunVersion to vercel.json:
{
"bunVersion": "1.x"
}
Set the middleware runtime to nodejs — Bun replaces the Node.js runtime transparently:
export const config = {
runtime: 'nodejs', // Bun swaps in when bunVersion is set
};
Bun reduces average latency by ~28% in CPU-bound workloads. Currently in Public Beta — supports Next.js, Express, Hono, and Nitro.
Basic Example
// middleware.ts (project root)
import { geolocation, rewrite } from '@vercel/functions';
export default function middleware(request: Request) {
const { country } = geolocation(request);
const url = new URL(request.url);
url.pathname = country === 'US' ? '/us' + url.pathname : '/intl' + url.pathname;
return rewrite(url);
}
export const config = {
runtime: 'edge', // 'edge' (default) | 'nodejs'
};
Helper Methods (@vercel/functions)
For non-Next.js frameworks, import from @vercel/functions:
| Helper | Purpose |
|---|---|
next() |
Continue middleware chain (optionally modify headers) |
rewrite(url) |
Transparently serve content from a different URL |
geolocation(request) |
Get city, country, latitude, longitude, region |
ipAddress(request) |
Get client IP address |
waitUntil(promise) |
Keep function running after response is sent |
For Next.js, equivalent helpers are on NextResponse (next(), rewrite(), redirect()) and NextRequest (request.geo, request.ip).
Matcher Configuration
Middleware runs on every route by default. Use config.matcher to scope it:
// Single path
export const config = { matcher: '/dashboard/:path*' };
// Multiple paths
export const config = { matcher: ['/dashboard/:path*', '/api/:path*'] };
// Regex: exclude static files
export const config = {
matcher: ['/((?!_next/static|favicon.ico).*)'],
};
Tip: Using matcher is preferred — unmatched paths skip middleware invocation entirely (saves compute).
Common Patterns
IP-Based Header Injection
import { ipAddress, next } from '@vercel/functions';
export default function middleware(request: Request) {
return next({ headers: { 'x-real-ip': ipAddress(request) || 'unknown' } });
}
A/B Testing via Edge Config
import { get } from '@vercel/edge-config';
import { rewrite } from '@vercel/functions';
export default async function middleware(request: Request) {
const variant = await get('experiment-homepage'); // <1ms read
const url = new URL(request.url);
url.pathname = variant === 'B' ? '/home-b' : '/home-a';
return rewrite(url);
}
Background Processing
import type { RequestContext } from '@vercel/functions';
export default function middleware(request: Request, context: RequestContext) {
context.waitUntil(
fetch('https://analytics.example.com/log', { method: 'POST', body: request.url })
);
return new Response('OK');
}
Request Limits
| Limit | Value |
|---|---|
| Max URL length | 14 KB |
| Max request body | 4 MB |
| Max request headers | 64 headers / 16 KB total |
Three CDN Routing Mechanisms
Vercel's CDN supports three routing mechanisms, evaluated in this order:
| Order | Mechanism | Scope | Deploy Required | How to Configure |
|---|---|---|---|---|
| 1 | Bulk Redirects | Up to 1M static path→path redirects | No (runtime via Dashboard/API/CLI) | Dashboard, CSV upload, REST API |
| 2 | Project-Level Routes | Headers, rewrites, redirects | No (instant publish) | Dashboard, API, CLI, Vercel SDK |
| 3 | Deployment Config Routes | Full routing rules | Yes (deploy) | vercel.json, vercel.ts, next.config.ts |
Project-level routes (added March 2026) let you update routing rules — response headers, rewrites to external APIs — without triggering a new deployment. They run after bulk redirects and before deployment config routes. Available on all plans.
Project-Level Routes — Configuration Methods
Project-level routes take effect instantly (no deploy required). Four ways to manage them:
| Method | How |
|---|---|
| Dashboard | Project → CDN → Routing tab. Live map of global traffic, cache management, and route editor in one view. |
| REST API | GET/POST/PATCH/DELETE /v1/projects/{projectId}/routes — 8 dedicated endpoints for CRUD on project routes. |
| Vercel CLI | Managed via vercel.ts / @vercel/config commands (compile, validate, generate). |
| Vercel SDK | @vercel/config helpers: routes.redirect(), routes.rewrite(), routes.header(), plus has/missing conditions and transforms. |
Use project-level routes for operational changes (CORS headers, API proxy rewrites, A/B redirects) that shouldn't require a full redeploy.
Programmatic Configuration with vercel.ts
Instead of static vercel.json, you can use vercel.ts (or .js, .mjs, .cjs, .mts) with the @vercel/config package for type-safe, dynamic routing configuration:
// vercel.ts
import { defineConfig } from '@vercel/config';
export default defineConfig({
rewrites: [
{ source: '/api/:path*', destination: 'https://backend.example.com/:path*' },
],
headers: [
{ source: '/(.*)', headers: [{ key: 'X-Frame-Options', value: 'DENY' }] },
],
});
CLI commands:
npx @vercel/config compile— compile to JSON (stdout)npx @vercel/config validate— validate and show summarynpx @vercel/config generate— generatevercel.jsonlocally for development
Constraint: Only one config file per project — vercel.json or vercel.ts, not both.
When to Use
- Geo-personalization of static pages (runs before cache)
- A/B testing rewrites with Edge Config
- Custom redirects based on request properties
- Header injection (CSP, CORS, custom headers)
- Lightweight auth checks (defense-in-depth only — not sole auth layer)
- Project-level routes for headers/rewrites without redeploying
When NOT to Use
- Need full Node.js APIs in Next.js → use
proxy.ts - General compute at the edge → use Edge Functions
- Heavy business logic or database queries → use server-side framework features
- Auth as sole protection → use Layouts, Server Components, or Route Handlers
- Thousands of static redirects → use Bulk Redirects (up to 1M per project)
References
- 📖 docs: https://vercel.com/docs/routing-middleware
- 📖 API reference: https://vercel.com/docs/routing-middleware/api
- 📖 getting started: https://vercel.com/docs/routing-middleware/getting-started
版本历史
- 11c74d6 当前 2026-07-19 09:52
