Vercel与Turbo联用时使用旧环境变量问题求助

核心问题 #

在新团队部署Turbo项目时，GOOGLE_API_CREDENTIALS始终读取旧值，即使已在Vercel和turbo.json中配置新变量，且构建时使用了yarn build --force --no-cache参数。

排查步骤 #

1. 确认Vercel环境变量的生效优先级 #

• 检查Vercel项目的环境变量配置：
  • 确保新的GOOGLE_API_CREDENTIALS是在当前团队的项目下设置的，而非全局账号或其他项目
  • 确认变量的环境类型（Production/Preview/Development）与部署环境匹配
  • 检查是否存在变量重写：Vercel的环境变量优先级为「项目环境变量 > 全局环境变量 > .env文件」，若项目中存在.env.production等本地文件，可能覆盖线上配置，需删除或注释相关硬编码值

2. 验证Turbo缓存的彻底清除 #

• 虽然使用了--no-cache和--force，但Turbo可能存在远程缓存残留：
  • 在Vercel控制台的构建日志中搜索「turbo cache」，确认是否命中了远程缓存
  • 执行turbo cache clean命令手动清除本地+远程缓存，再重新触发部署
  • 检查turbo.json的globalDependencies配置是否正确：

    {
      "globalDependencies": [
        "turbo.json",
        ".env*" // 若使用本地env文件，需加入依赖
      ]
    }
    

3. 检查构建命令的实际执行逻辑 #

• 确认package.json中的build命令是否被正确解析：
  • 确保build命令是turbo build而非其他自定义脚本，避免参数传递失效
  • 在Vercel构建日志中查看实际执行的命令，确认--force和--no-cache是否被正确附加
  • 尝试直接在Vercel的「构建命令」中手动输入yarn turbo build --force --no-cache，跳过package.json的脚本层

4. 排查环境变量的注入时机 #

• 确认Turbo是否在构建阶段正确读取环境变量：
  • 在turbo.json的env配置中，确保GOOGLE_API_CREDENTIALS被明确声明：

    {
      "pipeline": {
        "build": {
          "env": ["GOOGLE_API_CREDENTIALS"]
        }
      }
    }
    

  • 在项目的构建脚本中添加日志，输出process.env.GOOGLE_API_CREDENTIALS的前几位字符，验证变量是否在构建时被正确注入
  • 检查是否存在静态编译：若项目将环境变量编译进静态文件（如React的REACT_APP_*变量），需确保构建时变量已正确替换，而非使用旧的编译产物

5. 检查Vercel项目的缓存策略 #

• Vercel自身可能存在构建缓存残留：
  • 在Vercel项目的「设置 > 构建与开发设置」中，关闭「构建缓存」选项，重新触发部署
  • 检查是否存在部署缓存：删除Vercel的旧部署版本，重新发起全新部署

6. 验证代码层面的变量引用 #

• 检查项目代码中是否存在硬编码或默认值：
  • 全局搜索GOOGLE_API_CREDENTIALS，确认是否有代码直接赋值旧值，或使用了默认 fallback 值
  • 检查是否存在本地.env文件被提交到Git仓库，导致部署时加载旧值，需将.env*加入.gitignore

内容的提问来源于stack exchange，提问作者rohit kumar