Vercel部署警告：项目构建设置因配置文件含builds无法生效求助

一、警告原因及消除方案 #

这个警告的核心逻辑很直接：Vercel会优先读取vercel.json里的builds字段配置，忽略项目面板中设置的构建/开发参数。你有两种方式处理：

方案1：移除builds字段，改用项目面板统一配置 #

如果希望项目面板的构建设置生效，直接删除vercel.json中的builds数组，保留routes和env部分即可：

{
    "version": 2,
    "routes": [
      {
        "src": "/(.*)",
        "dest": "/index.html"
      }
    ],
    "env": {
      "RUBY_ENV": "production"
    }
}

然后到Vercel项目面板的「构建与开发设置」中配置：

• 构建命令：填入你的vercel-build.sh（或者直接写脚本内的具体命令，比如bundle install && jekyll build）
• 输出目录：根据项目类型填写（比如Jekyll项目填_site）
• 框架预设：选择「Ruby」或「Other」（自定义脚本场景）

方案2：保留builds字段，忽略警告 #

如果想继续用vercel.json管理构建规则，这个警告只是提示性信息，不会影响构建流程。但要确保builds配置正确：

• 给vercel-build.sh添加执行权限：本地执行chmod +x vercel-build.sh后提交到仓库
• 脚本内的命令要能完整完成构建流程（比如依赖安装、产物生成）

如果是Rack类Ruby应用，还可以直接指定入口文件，不用自定义脚本：

{
    "version": 2,
    "builds": [
      {
        "src": "config.ru",
        "use": "@vercel/ruby@1" // 指定具体版本更稳定
      }
    ],
    "routes": [
      {
        "src": "/(.*)",
        "dest": "/index.html"
      }
    ],
    "env": {
      "RUBY_ENV": "production"
    }
}

二、@vercel/ruby构建最佳实践 #

• 锁定Ruby版本：在项目根目录添加.ruby-version文件，写入所需版本（比如3.2.2），Vercel会自动匹配安装
• 规范依赖管理：用Gemfile和Gemfile.lock锁定依赖版本，避免构建时出现版本不一致问题；静态站点（如Jekyll）要确保Gemfile包含jekyll等核心依赖
• 优化自定义构建脚本：如果用vercel-build.sh，注意：
  • 开头加#!/bin/bash指定解释器
  • 开启错误检测（set -e），确保出错时终止构建
    示例脚本：

  #!/bin/bash
  set -e
  bundle install --path vendor/bundle
  bundle exec jekyll build
  

• 环境变量配置：敏感信息（如API密钥）优先在Vercel项目面板的「环境变量」中设置，vercel.json的env字段适合配置非敏感全局变量（如RUBY_ENV）

三、验证配置有效性 #

部署完成后可以通过以下方式确认配置正常：

• 查看构建日志，确认构建命令按预期执行
• 访问部署后的站点，验证页面加载正常
• 在构建脚本中添加echo $RUBY_ENV，查看日志是否输出production，确认环境变量生效

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