nuxtjs/vercel-builder 常见错误与迁移 Nuxt 3 完全清单告别 Legacy 的最佳实践【免费下载链接】vercel-builderVercel Builder for Nuxt项目地址: https://gitcode.com/gh_mirrors/ve/vercel-buildernuxtjs/vercel-builder是 Nuxt 2 应用部署到 Vercel 的专用构建器它会把你的 Nuxt 2 SSR 应用打包成可自动伸缩的 Serverless 函数。官方已明确标注它是一个Legacy遗留构建器仅支持 Nuxt 2并强烈建议迁移到 Nuxt Bridge 或直接使用 Nuxt 3。这篇文章整理了部署 nuxtjs/vercel-builder 时最常见的报错与解决办法并附上一份迁移 Nuxt 3 的完全清单帮你快速告别 Legacy。 使用前提nuxtjs/vercel-builder 适合谁在排查任何错误前先确认你的项目类型避免方向性错误仅面向 Nuxt 2 的 SSR 应用纯静态生成的 Nuxt 2 应用无需使用它Vercel 零配置即可部署通过vercel.json的builds字段指定该构建器以nuxt.config.js或.ts作为构建入口内置node_modules与 yarn 全局缓存机制见 src/prepare-cache.ts配合多阶段构建部署产物更小、构建更快⚠️ 如果你的项目已经是 Nuxt 3 / Nuxt Bridge请跳过本文排查部分直接看第四节的迁移清单——正确做法是删掉这个构建器⚙️ 最快配置方法一份最小可用的 vercel.json最小配置只需几行完整可部署示例见 examples/basic/vercel.json{ version: 2, builds: [ { src: nuxt.config.js, use: nuxtjs/vercel-builder } ] }src只允许是package.json、nuxt.config.js或nuxt.config.ts三者之一写错入口是最常见的部署失败原因。常用config配置项速查配置项作用serverFiles把 webpack 不打包的文件本地模块、serverMiddleware 等带入 Lambda支持 globinternalServer手动开关 Lambda 内部服务器localhost:3000配合serverMiddleware使用generateStaticRoutes构建时用nuxt generate预渲染静态路由tscOptions覆盖tsconfig.json的 TS 编译参数memory/maxDuration自定义 Serverless 函数的内存与执行时长此外如果你在package.json的scripts中定义了vercel-build脚本构建器会在构建时自动执行它适合加入自定义构建步骤。 常见部署错误排查清单10 类高频报错速查1. 入口src写错报错Specified src for nuxtjs/vercel-builder has to be package.json, nuxt.config.js or nuxt.config.ts解决builds中指向的文件名不对或不存在。入口校验逻辑见 src/utils.ts把src改为项目入口目录下真实的nuxt.config.jsTS 项目为nuxt.config.ts即可。2. 缺少 nuxt 依赖报错No nuxt dependency found in package.json构建器会在部署包中把nuxt替换为nuxt/core见 src/utils.ts因此nuxt必须声明在dependencies或devDependencies中。monorepo 场景注意构建器读取的是入口所在目录的package.json。3. 找不到 nuxt.config报错Can not read nuxt.config from /path/to/project解决入口目录下必须存在nuxt.config.js或nuxt.config.ts。monorepo 中请确认src指向正确的子包路径例如www/nuxt.config.js可参考 test/fixture/now.json 的写法。4. 加载 Nuxt 配置失败报错Could not load Nuxt configuration. Make sure all dependencies are listed in package.json dependencies or in serverFiles within builder options原因nuxt.config.js里引用的模块、插件或包没有被打进 Lambda报错信息定义于 src/launcher.ts。解决把用到的依赖从devDependencies挪到dependencies自定义中间件、本地模块文件加入serverFiles本地模块不要以字符串形式引用.ts原文件见错误 65. 私有 npm 模块拉取失败解决在vercel.json中把NPM_AUTH_TOKEN或NPM_TOKEN配置为构建环境变量build.env或者把整个.npmrc内容内联到NPM_RC环境变量中。6. TypeScript 项目的两类典型坑编译期报错Can not read tsconfig.json入口目录必须存在tsconfig.json如需针对部署单独调整参数可放一个tsconfig.vercel.json其compilerOptions会与tscOptions合并见 src/typescript.ts运行期异常构建器只对nuxt.config.ts、本地modules、serverMiddleware做预编译modules/serverMiddleware之外的字符串若引用.ts原文件会引发难以定位的报错建议统一引用编译产物7. serverMiddleware 在生产环境消失serverMiddleware指向的文件不在 webpack 打包范围内必须通过serverFiles手动带入例如{ config: { serverFiles: [server-middleware/**] } }配置后构建器会自动开启内部服务器你的接口在 Lambda 内可通过http://localhost:3000访问内部服务器实现见 src/launcher.ts。8. 环境变量改了不生效构建期通过env读取的变量是打包时写死的在 Vercel 控制台修改后必须重新部署且变量需声明进vercel.json的build.env运行期变量用顶层env设为true表示自动暴露Nuxt 2.13 推荐统一改用runtimeConfig构建期 / 运行期取值更省心9. monorepo 构建读取根目录外文件失败在 Vercel 项目设置的Root Directory区域勾选 Include source files outside of the Root Directory in the Build Step双 Nuxt 应用并排部署示例见 examples/side-by-side/README.md10. Lambda 体积超出限制构建器默认单个 Lambda 上限为50MB见 src/config.ts。瘦身手段优先使用yarn安装依赖autoclean 会自动清理无用包显著减小体积serverFiles只带必需文件关闭不必要的 sourcemaptscOptions: { sourceMap: false }。 Nuxt 2 迁移 Nuxt 3 完全清单5 步告别 Legacy第 11 个最常见错误其实是——Nuxt 3 项目还在配置这个构建器。Nuxt 3 基于 Nitro对 Vercel 是零配置部署继续保留旧构建器只会报错或产出错误产物。按顺序执行以下清单即可完成迁移1. 升级依赖nuxt升级到 3.x移除nuxtjs/vercel-builder依赖2. 清理旧配置vercel.json中删掉整个builds数组及相关的src/use指向仅保留仍需要的routes与env3. 确认 Nitro presetNuxt 3 在 Vercel 上自动使用vercelpreset通常无需任何额外配置4. 迁移目录约定api/目录下的独立 Serverless 函数可原样保留serverMiddleware迁移到 Nitro 的服务端路由方案5. 回归验证重点检查 ①runtimeConfig构建期 / 运行期取值 ② 静态资源路径 ③ 冷启动日志中的初始化耗时✅ 迁移后你得到什么零配置部署不需要builds、不需要 builder推送代码即构建上线最新 Build API缓存、边缘能力等 Vercel 新特性全部可用而 Legacy builder 已停止演进当前版本停留在 package.json 中的 0.25.0更小的产物与更快的冷启动Nitro 针对 Serverless 环境做了深度优化更低的维护成本不再需要手动维护serverFiles、缓存目录与 TS 预编译规则 附本文涉及的源码与示例路径文件说明src/index.ts构建器入口暴露 build / config / prepareCachesrc/utils.tssrc入口校验、nuxt 依赖检查与生产包改写src/launcher.tsLambda 冷启动流程与 Nuxt 配置加载src/typescript.tsTS 编译参数合并tsconfig.vercel.jsonsrc/prepare-cache.ts构建缓存目录收集NUXT_CACHE_DISABLED1可关闭examples/basic/可部署的基础示例含vercel dev本地调试配置examples/side-by-side/monorepo 双 Nuxt 应用并排部署示例test/fixture/测试 fixture可参考其最小化构建配置写法【免费下载链接】vercel-builderVercel Builder for Nuxt项目地址: https://gitcode.com/gh_mirrors/ve/vercel-builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考