企业官网建设流程全解析

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

【免费下载链接】vercel-builderVercel Builder for Nuxt项目地址: https://gitcode.com/gh_mirrors/ve/vercel-builder

@nuxtjs/vercel-builder是 Nuxt 2 应用部署到 Vercel 的官方构建器，帮你把 Nuxt 2 SSR 应用打包成可自动扩缩容的 Serverless 函数。而新手踩坑最多的，就是在vercel.json的env、build.env和 Nuxt 的runtimeConfig三个配置入口之间反复横跳。这篇清单帮你一次理清：构建时变量放哪里、运行时变量放哪里、什么情况下必须重新部署。

一、先看懂三个入口：一张表搞清 env、build.env 与 runtimeConfig

核心记忆点：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 控制台改值后必须重新触发一次部署才会生效。这也是新手最常问"为什么我改了变量不生效"的根源。

三、runtimeConfig：Nuxt 2.13+ 的推荐选择

从 Nuxt 2.13 开始，官方推荐用runtimeConfig替代裸process.env：

• 服务端：通过context.app.runtimeConfig读取
• 客户端：只有明确放进public段的字段才会被暴露
• 部署时可在 Vercel 环境变量中注入，多数情况无需重新构建即可生效

选择口诀：

1. 变量只在本地构建流程用 →build.env
2. 变量在SSR 运行时用、前后端都要 →runtimeConfig
3. 只是给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，运行用 runtimeConfig，Lambda 进程用 env；构建时变量改完必须重部署。

把这张清单贴在vercel.json旁边，环境变量相关的部署故障基本可以绝迹。

【免费下载链接】vercel-builderVercel Builder for Nuxt项目地址: https://gitcode.com/gh_mirrors/ve/vercel-builder