Vercel 环境变量配置
关于 .env 文件和 vercel env 命令的问题,得到层级规则、正确命令与密钥配置排查方案。
功能与用途
Vercel 项目里环境变量最容易出三类问题:密钥被提交进仓库或误加了 NEXT_PUBLIC_ 前缀泄露到浏览器、新机器拉代码后 .env.local 缺键跑不起来、本地 OIDC 令牌大约 12 小时过期后突然认证失败。这个技能讲清 .env 文件的层级与加载顺序、vercel env pull/add/ls/rm 的正确用法、bootstrap 时的 link 与核对流程,以及 pull 会覆盖自定义变量这类坑。需要本机装了 Vercel CLI 并登录。
适用场景
- 刚克隆仓库到新机器,本地跑不起来,因为 .env.local:刚克隆仓库到新机器,本地跑不起来,因为 .env.local 里缺了一批键
- 本地开发跑了几小时后突然认证失败,怀疑是 OIDC 令牌过期:本地开发跑了几小时后突然认证失败,怀疑是 OIDC 令牌过期
- 用 vercel env pull 之后自己手动加的几个调试:用 vercel env pull 之后自己手动加的几个调试变量全没了,想搞清楚原因和规避办法
- 需要给 staging 分支单独配一个数据库地址,不想影响 :需要给 staging 分支单独配一个数据库地址,不想影响 preview 和 production
适用人群
- 部署在 Vercel 上的 Next.js 开发
- 负责项目密钥与部署配置的运维工程师
- 刚接手项目需要在新机器启动开发环境的前端工程师
使用步骤
- 说明当前情况:是新机器启动、密钥配置、命令用法还是认证报错
- 得到对应的 .env 文件层级与 Next.js 加载顺序说明,确认变量该放哪个文件
- 按给出的 vercel env 命令执行,如 vercel link 后 vercel env pull .env.local --yes 拉取变量
- 用 .env.example 逐键核对 .env.local 是否有缺失,必要时重跑一步
- 遇到 OIDC 报错按症状对照表处理,重新 pull 换取新令牌;自定义变量另存到 .env.development.local 防覆盖
开始使用
将需求和 Skill 名称发送给已连接 SkillPX MCP 的 AI 助手,核对适用工具和安装要求。
技术信息
- 分类
- 编程
- 适用工具
- Codex、Claude Code、OpenClaw、Hermes、国内 Agent
- 使用难度
- 进阶
- 版本
- main
- 最近更新
- 2026-09-18
- 文件数
- 3
- 安装包大小
- 自动生成 ZIP
- 安全检查
- 基础检查通过
Vercel environment variable expert guidance. Use when working with .env files, vercel env commands, OIDC tokens, or managing environment-specific configuration.
使用前准备
- 需要 Vercel 账号、本机安装并登录 Vercel CLI,且项目已完成 link。
依赖与权限
- MY_SECRET
- VERCEL_OIDC_TOKEN
- AI_GATEWAY_API_KEY
- DATABASE_URL
- 读取用户主动提供的内容