用途:Vercel Routing Middleware 是平台级请求拦截层,在缓存之前运行于每个匹配配置的请求,适用于 Next.js、SvelteKit、Astro、Nuxt 等任意框架,基于 Fluid Compute。入口为项目根目录的 middleware.ts 或 middleware.js,必须默认导出函数(函数名任意)。
主要能力:可做重写、重定向、地理定位个性化、A/B 测试、请求头注入与轻量鉴权检查。非 Next.js 框架从 @vercel/functions 导入 next()、rewrite()、geolocation()、ipAddress()、waitUntil() 等辅助方法;Next.js 使用 NextResponse 与 NextRequest 上的等价方法。
用法与配置:运行时可设 edge(默认)、nodejs,Bun 需在 vercel.json 加 bunVersion 并设 runtime 为 nodejs。默认对所有路由生效,建议用 config.matcher 限定路径。请求限制:URL 最长 14 KB、请求体最大 4 MB、请求头最多 64 个或合计 16 KB。CDN 路由机制依次为 Bulk Redirects、项目级路由、部署配置路由;项目级路由无需重新部署,可通过 Dashboard、REST API、Vercel CLI 或 @vercel/config SDK 管理。vercel.ts 配合 @vercel/config 可做类型安全配置,CLI 提供 compile、validate、generate;每个项目只能有一个配置文件(vercel.json 或 vercel.ts)。
适用场景:静态页面地理个性化、基于 Edge Config 的 A/B 重写、按请求属性的自定义重定向、CSP/CORS 等响应头注入、无需重新部署的操作性路由变更。
限制:Next.js 16 已将 middleware.ts 重命名为 proxy.ts(仅 Node.js,需同步重命名导出函数,迁移可用 npx @next/codemod@latest middleware-to-proxy),middleware.ts 仍可用但已弃用并会告警。不应把中间件作为唯一鉴权层,需完整 Node.js API 的场景应改用 proxy.ts,通用边缘计算用 Edge Functions,重型业务逻辑或数据库查询用服务端框架能力,海量静态重定向用 Bulk Redirects。