使用GitHub Actions部署FastAPI到Vercel时，--prebuilt参数导致.vercel/output/builds.json文件找不到的问题

问题描述 #

我尝试用GitHub Actions把FastAPI应用部署到Vercel，不用--prebuilt标签时部署成功。但根据Vercel文档的说明，--prebuilt标签应该能避免把全部源码部署到Vercel，所以我想用这个参数。现在的问题是，明明vercel build命令已经生成了.vercel/output/builds.json，但Vercel却检测不到这个文件/文件夹。

执行的命令 #

vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

错误信息 #

Error: ENOENT: no such file or directory, lstat '/vercel/path0/.vercel/output/builds.json'

项目结构 #

api
  |-- routes
  |      |-- middleware.py
  |      |-- auth_route.py
  |      |-- ...
  |-- main.py
tests
  |-- unit_tests
  |       |-- test_main.py
  |       |-- test_auth_route.py
  |       |-- ...
requirements.txt
README.md
vercel.json

vercel.json配置 #

{
  "routes": [
    {
      "src": "/(.*)",
      "dest": "api/main.py"
    }
  ]
}

GitHub Actions配置（ci.yml） #

name: Run Tests and Deploy to Vercel

on:
  push:
    branches:
      - main

jobs:
  run_tests:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v2

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11.5'

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt

    - name: Run tests
      run: |
        pytest

    # deploy to vercel
    - name: Install Vercel CLI
      run: npm install --global vercel@latest

    - name: Pull Vercel Environment Information
      run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}

    - name: Build Project Artifacts
      run: vercel build --token=${{ secrets.VERCEL_TOKEN }}

    - name: Deploy Project Artifacts to Vercel
      run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

本地复现情况 #

我在本地用Vercel CLI构建和部署时也遇到了同样的问题，即使本地目录里确实存在.vercel/output/builds.json文件：

(fastapi_env) (base) redhorseacademyPC:fastapi_demo redhorseacademy$ vercel build
Vercel CLI 39.1.2
WARN! Due to `builds` existing in your configuration file, the Build and Development Settings defined in your Project Settings will not apply. Learn More: https://vercel.link/unused-build-settings
Installing required dependencies...
✅  Build Completed in .vercel/output [9s]
(fastapi_env) (base) redhorseacademyPC:fastapi_demo redhorseacademy$ vercel deploy --prebuilt --archive=tgz
Vercel CLI 39.1.2
  Inspect: https://vercel.com/redhorseacademy-projects/fastapi_demo/D7sF6esFWwpRLEbhCRdibYFNKyCn [6m]
✅  Preview: https://fastapidemo-38s604pe3-redhorseacademy-projects.vercel.app [6m]
Error: ENOENT: no such file or directory, lstat '/vercel/path0/.vercel/output/builds.json'

生成的builds.json内容 #

{
  "//": "This file was generated by the `vercel build` command. It is not part of the Build Output API.",
  "target": "preview",
  "argv": [
    "/usr/local/bin/node",
    "/usr/local/bin/vercel",
    "build"
  ],
  "builds": [
    {
      "require": "@vercel/python",
      "requirePath": "/usr/local/lib/node_modules/vercel/node_modules/@vercel/python/dist/index.js",
      "apiVersion": 3,
      "src": "app/main.py",
      "use": "@vercel/python"
    }
  ]
}

我已经尝试了相关讨论里提到的解决方案，也看了类似的Issue，但除了移除--prebuilt参数之外，没找到能解决问题的方法，不过我还是想保留这个参数来避免上传源码。

解决方案建议 #

我帮你梳理几个可能的解决方向，你可以逐一尝试：

1. 修正builds.json中的路径错误 #

你看生成的builds.json里，src字段写的是app/main.py，但你的项目实际入口是api/main.py，这明显是路径不匹配！Vercel预构建后会依据这个路径查找资源，路径不对不仅会导致文件找不到，还可能干扰builds.json的正常识别逻辑。

你可以试试：

• 本地先删除.vercel文件夹，重新执行vercel build，确认生成的builds.json中src是否变为api/main.py
• 在GitHub Actions的vercel pull步骤后，添加清理缓存的操作：rm -rf .vercel，再执行vercel build

2. 显式指定构建输出目录 #

执行vercel build时，通过--output参数明确指定输出目录，确保构建产物路径正确：

vercel build --output .vercel/output --token=${{ secrets.VERCEL_TOKEN }}

然后在部署时，显式指定项目根目录，让Vercel能准确定位.vercel文件夹：

vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }} --cwd .

3. 固定GitHub Actions的工作目录 #

有时候GitHub Actions的工作目录会发生变化，导致后续步骤找不到上一步生成的.vercel文件夹。你可以在vercel build和vercel deploy步骤中，都加上working-directory: .，确保两个步骤在同一目录执行：

- name: Build Project Artifacts
  run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
  working-directory: .

- name: Deploy Project Artifacts to Vercel
  run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}
  working-directory: .

4. 调整Vercel CLI版本 #

你当前使用的Vercel CLI 39.1.2可能存在预构建路径识别的bug。可以试试升级到最新版，或者降级到38.x版本，比如安装时指定版本：

npm install --global vercel@38.0.0

不同版本的CLI对Build Output API的处理逻辑有差异，换个版本说不定能解决问题。

5. 在vercel.json中显式配置builds #

你可以在vercel.json中添加builds字段，明确指定Python入口路径，避免Vercel自动识别路径出错：

{
  "routes": [
    {
      "src": "/(.*)",
      "dest": "api/main.py"
    }
  ],
  "builds": [
    {
      "src": "api/main.py",
      "use": "@vercel/python"
    }
  ]
}

这样Vercel构建时会直接使用你指定的路径，不会误识别为app/main.py了。

备注：内容来源于stack exchange，提问作者gmartinsnull