Vercel Next.js 构建警告解析Legacy Routes 导致 Optimized Lambdas 被禁用的原因与迁移指南【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercelvercel/next构建器默认会将 Next.js 页面打包进优化后的函数Optimized Lambdas以缩短冷启动时间、提升整体吞吐量但当项目在now.json或vercel.json中声明了旧版routes配置时该优化会被自动关闭并输出一条构建期警告。本文结合本仓库vercel/next构建器的源码与测试夹具解释这条警告的触发机制并给出迁移到rewrites/redirects/headers新式配置的完整实操方案帮助你在保留自定义路由能力的同时重新获得优化函数的收益。警告是什么一次构建期的显式降级提示当构建日志中出现如下警告时说明你的 Next.js 项目被vercel/next构建器判定为“因旧版routes配置而退出 Optimized Lambdas 模式”WARNING: your application is being opted out of vercel/nexts optimized lambdas mode due to legacy routes in vercel.json. http://err.sh/vercel/vercel/next-legacy-routes-optimized-lambdas这是一条显式的降级提示而非部署失败。它的含义是项目仍会正常部署与运行但页面不再被合并进优化后的共享函数而是退回传统的构建/路由方式优化收益更快的启动时间、更高的应用吞吐量因此损失。仓库中的错误文档 errors/next-legacy-routes-optimized-lambdas.md 对本警告做了官方说明并指出修复方向是迁移到新式路由配置。为什么会有这个警告两种路由机制的冲突要理解这条警告需要先厘清两个概念1. Optimized Lambdas优化函数vercel/next默认会把页面打包进优化后的函数中多个页面共享同一 Lambda。这种共享模式能够最小化启动时间并提高整体吞吐量——这是该构建器的默认且推荐行为。2. Legacy Routes旧版路由在now.json/vercel.json中直接声明的顶层routes数组采用src/dest正则匹配方式例如本仓库测试夹具 packages/next/test/fixtures/00-legacy-routes-nested/vercel.json 中的写法{ version: 2, builds: [{ src: apps/app/package.json, use: vercel/next }], routes: [ { src: /(.*), dest: /apps/app/$1 } ] }冲突的本质Legacyroutes会在平台路由层插入一层自定义的请求转发/改写规则这与vercel/next内部为 Optimized Lambdas 生成的路由编排包括针对routes-manifest.json转换出的rewrites、redirects、headers以及动态页面映射等存在顺序与语义上的冲突。构建器无法保证两者叠加后的行为一致因此选择直接退出优化以确保路由正确性优先于性能优化。源码证据警告的触发逻辑警告的检测与降级逻辑位于 packages/next/src/index.ts。构建器先判断应用是否处于服务端模式isServerMode取决于 Next.js 版本是否达到SERVER_BUILD_MINIMUM_NEXT_VERSION仅在非服务端模式即传统 serverless 构建路径下才执行该检查let hasLegacyRoutes false; if (isServerMode) { // server mode 下不做此检查 } else { if (nowJsonPath) { const nowJsonData JSON.parse(await readFile(nowJsonPath, utf8)); if (Array.isArray(nowJsonData.routes) nowJsonData.routes.length 0) { hasLegacyRoutes true; console.warn( WARNING: your application is being opted out of vercel/nexts optimized lambdas mode due to legacy routes in ${path.basename( nowJsonPath )}. http://err.sh/vercel/vercel/next-legacy-routes-optimized-lambdas ); } } // ... }从源码可确认两个关键事实触发条件是存在非空routes数组Array.isArray(nowJsonData.routes) nowJsonData.routes.length 0即只要配置文件中声明了至少一条旧版路由就会置hasLegacyRoutes true并输出警告。检测对象同时覆盖now.json与vercel.json构建器通过nowJsonPath读取配置文件因此无论你使用的是旧的项目配置文件还是vercel.json命中规则相同。降级后的实际影响sharedLambdas 计算hasLegacyRoutes并非只影响一条警告信息它直接参与是否启用共享 Lambda的决策。在 packages/next/src/index.ts 中// default to true but still allow opting out with the config const isSharedLambdas !isServerMode !hasLegacyRoutes !hasFunctionsConfig typeof config.sharedLambdas undefined ? true : !!config.sharedLambdas;也就是说只要hasLegacyRoutes为trueisSharedLambdas就不会采用默认的true而是回落到显式配置值未配置则为false从构建结果层面真正关闭了共享优化。同类警告functions 配置该检查块中还包含一个兄弟警告——当配置了顶层functions字段时同样会退出优化见 errors/next-functions-config-optimized-lambdas.mdWARNING: Your application is being opted out of vercel/next optimized lambdas mode due to functions config.排查时可以一并检查vercel.json中是否同时存在routes与functions两个字段两者都会触发降级。修复方案一迁移到 vercel.json 中的新式路由配置将旧版routes数组替换为平台原生支持的三个新式配置字段rewrites、redirects、headers。它们彼此职责清晰且不会触发优化退出逻辑。rewrites内部改写URL 不变{ version: 2, rewrites: [ { source: /old-page, destination: /new-page }, { source: /api/:path*, destination: /api-handler/:path* } ] }rewrites不会改变浏览器地址栏中的 URL适合在不对外暴露真实路径的前提下做请求转发。source支持:param命名参数与*通配符。redirects外部跳转URL 变化{ version: 2, redirects: [ { source: /old, destination: /new, permanent: true }, { source: /redir/:path*, destination: /target/:path*, statusCode: 307 } ] }redirects会返回 3xx 状态码让客户端跳转到新地址。permanent为true时返回 308永久重定向为false或省略时返回 307临时重定向也可以通过statusCode显式指定。headers响应头注入{ version: 2, headers: [ { source: /api/(.*), headers: [ { key: X-Custom-Header, value: my-value }, { key: Cache-Control, value: s-maxage60 } ] } ] }headers用于按路径规则向响应注入自定义头适合安全头、缓存控制等场景同样不会触发降级。修复方案二迁移到 next.config.js 内置自定义路由如果路由规则本质上是 Next.js 应用自身的逻辑而非平台级转发更推荐直接在next.config.js中使用 Next.js 内置的自定义路由支持与页面、动态路由天然协同也无需在部署配置中重复维护// next.config.js module.exports { async rewrites() { return [ { source: /old-page, destination: /new-page }, { source: /api/:path*, destination: /api-handler/:path* } ]; }, async redirects() { return [ { source: /old, destination: /new, permanent: true } ]; }, async headers() { return [ { source: /api/:path*, headers: [{ key: X-Custom-Header, value: my-value }] } ]; } };vercel/next构建器在构建阶段会读取 Next.js 生成的routes-manifest.json并通过convertRedirects/convertRewrites/convertHeaders见 packages/next/src/index.ts 及 packages/next/src/index.ts将其转换为平台路由。这意味着在next.config.js中声明的路由会被构建器主动拾取并纳入 Optimized Lambdas 的路由编排不构成冲突。两条迁移路径的选择建议场景推荐方案路由属于 Next.js 应用逻辑页面/API 改写、跳转、响应头next.config.js中的rewrites/redirects/headers路由属于平台/部署层策略如 monorepo 子应用分发vercel.json中的rewrites/redirects/headers二者混用优先使用前者平台层仅保留必要的转发规则如何验证修复生效迁移完成后重新部署观察构建日志警告消失日志中不再出现optimized lambdas mode due to legacy routes字样说明已恢复 Optimized Lambdas 模式路由行为正确逐一验证原本由routes承担的重定向、改写、响应头行为在新配置下结果一致。仓库测试夹具提供了可对照的验证思路packages/next/test/fixtures/07-custom-routes/vercel.json 是一个新式自定义路由的集成测试夹具其中通过probes断言了重定向状态码307/308、改写后的页面内容、响应头注入等行为并通过logMustNotContain显式断言日志中不得出现两条优化退出警告logMustNotContain: WARNING: your application is being opted out of vercel/nexts optimized lambdas mode due to legacy routespackages/next/test/fixtures/00-shared-lambdas/vercel.json 是共享 Lambda 场景的夹具同样断言动态路由正常且不出现降级警告packages/next/test/fixtures/00-legacy-routes-nested/vercel.json 则是反向用例它使用旧版routes数组src: /(.*)→dest: /apps/app/$1可用于观察警告的触发形态。常见误区与注意事项警告不等于部署失败应用仍可正常访问只是失去了优化收益但建议尽快迁移避免长期以非优化形态运行。不要混用新旧两套路由一旦routes数组存在哪怕只有一条构建器即判定为 legacy 模式其余新式配置也会被这一判断拖累。注意适用范围该检测仅作用于非服务端模式legacy serverless 构建路径的 Next.js 应用。较新版本 Next.js 走服务端模式时此警告不再适用见 packages/next/src/index.ts 中isServerMode分支逻辑。functions配置同样触发降级如果你的vercel.json中还配置了顶层functions字段请一并清理或确认必要性否则仍会命中同类的优化退出警告参考 errors/next-functions-config-optimized-lambdas.md。相关文档errors/next-legacy-routes-optimized-lambdas.md本警告的官方说明errors/next-functions-config-optimized-lambdas.mdfunctions配置触发的同类警告errors/now-next-legacy-mode.mdvercel/next传统部署模式说明packages/next/src/index.ts警告触发与isSharedLambdas决策的源码实现packages/next/test/fixtures/07-custom-routes/vercel.json 与 packages/next/test/fixtures/00-legacy-routes-nested/vercel.json新式/旧式路由的对照测试夹具【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考