routing-middleware
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.
- License 许可
- MIT
- 最近更新
- 2026-09-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- 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.
02 资源文件 1
- 参考文档agents/openai.yaml182 B
03 SKILL.md 正文
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
04 同仓库更多 Skills
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.
review-agent
Perform a read-only, defect-first review of a specified code change and return every actionable finding. Use when another agent delegates review of uncommitted changes, a base-branch diff, a commit, or custom review instructions.
plugin-creator
Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.
openai-docs
Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.