环境变量避坑清单：@nuxtjs/vercel-builder 中 env、build.env 与 runtimeConfig 如何取舍？

环境变量避坑清单nuxtjs/vercel-builder 中 env、build.env 与 runtimeConfig 如何取舍【免费下载链接】vercel-builderVercel Builder for Nuxt项目地址: https://gitcode.com/gh_mirrors/ve/vercel-buildernuxtjs/vercel-builder是 Nuxt 2 应用部署到 Vercel 的官方构建器帮你把 Nuxt 2 SSR 应用打包成可自动扩缩容的 Serverless 函数。而新手踩坑最多的就是在vercel.json的env、build.env和 Nuxt 的runtimeConfig三个配置入口之间反复横跳。这篇清单帮你一次理清构建时变量放哪里、运行时变量放哪里、什么情况下必须重新部署。一、先看懂三个入口一张表搞清 env、build.env 与 runtimeConfig配置位置生效时机适合放什么修改后需要重新部署build.envvercel.json构建时Build打进产物里的密钥、构建脚本用的令牌✅ 需要envvercel.json运行时RuntimeLambda 每次执行时读取的变量⚠️ 看代码读取方式runtimeConfignuxt.config运行时 可注入客户端前后端共用的配置、公开变量视是否固化而定核心记忆点build.env 是烤进蛋糕的糖构建完就定型env 是每次端上桌前撒的调料。二、build.env构建时变量的唯一正确姿势如果你的代码在构建阶段就要读环境变量比如 webpack 插件、构建脚本里用process.env读取变量必须声明在vercel.json的build.env中否则构建环境里根本看不到它。典型的场景 安装私有 npm 包在build.env中配置NPM_AUTH_TOKEN或NPM_TOKEN构建器会自动为你写入.npmrc见 src/build.ts 构建时固化的第三方 API 密钥⚠️最大陷阱通过process.env读取且被烘焙baked in进构建产物的变量在 Vercel 控制台改值后必须重新触发一次部署才会生效。这也是新手最常问为什么我改了变量不生效的根源。三、runtimeConfigNuxt 2.13 的推荐选择从 Nuxt 2.13 开始官方推荐用runtimeConfig替代裸process.env服务端通过context.app.runtimeConfig读取客户端只有明确放进public段的字段才会被暴露部署时可在 Vercel 环境变量中注入多数情况无需重新构建即可生效选择口诀变量只在本地构建流程用 →build.env变量在SSR 运行时用、前后端都要 →runtimeConfig只是给Lambda 进程用的系统级变量 →env四、高频避坑清单发布前逐条自查 ✅✅ 私有源令牌NPM_TOKEN放在了build.env而不是env✅ 改过构建时变量后重新执行了一次部署✅ 想暴露给浏览器的敏感变量绝没有放进runtimeConfig.public✅ 需要读取 Vercel 系统环境变量如 Analytics ID时确认已在配置中暴露构建器在 src/build.ts 中读取VERCEL_ANALYTICS_ID✅ 多应用 monorepo 中每个子应用各自nuxt.config.js的runtimeConfig都独立配置了五、Monorepo 与配套配置文件参考两个 Nuxt 应用共存一个仓库时vercel.json旧版为now.json里为每个nuxt.config.js配一个 build环境变量则统一在项目级配置。仓库里的示例可以直接对照学习examples/side-by-side/now.json —— 双应用并行部署的路由与构建配置examples/basic/vercel.json —— 含 API 函数与 serverFiles 的完整配置src/config.ts —— 构建器自身的 Lambda 打包限制50MB在 Vercel 项目设置中配置 Root Directory 时记得勾选将 Root 目录外的源文件纳入 Build Step这也是 monorepo 部署的常见坑点六、一句话总结构建用 build.env运行用 runtimeConfigLambda 进程用 env构建时变量改完必须重部署。把这张清单贴在vercel.json旁边环境变量相关的部署故障基本可以绝迹。【免费下载链接】vercel-builderVercel Builder for Nuxt项目地址: https://gitcode.com/gh_mirrors/ve/vercel-builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考