Flask手势猜拳游戏部署Vercel时遇文件大小超限问题

问题背景 #

我开发了一款基于Flask的石头剪刀布游戏，核心依赖如下：

from flask import Flask, render_template, Response, jsonify, request, redirect, url_for
import cv2
import cvzone
from cvzone.HandTrackingModule import HandDetector
import time
import random

应用通过摄像头识别用户手势实现与AI对战，但部署到Vercel时触发报错：

Error Message : Size of uploaded file exceeds 300MB

解决方案 #

1. 清理冗余文件与缓存 #

• 把本地开发产生的冗余目录加入.gitignore，避免提交到版本库：

  venv/
  __pycache__/
  *.pyc
  *.pyo
  *.pyd
  node_modules/
  .cache/
  

• 安装Python依赖时禁用缓存，减少本地缓存文件体积：

  pip install --no-cache-dir -r requirements.txt
  

2. 优化Python依赖 #

• 用opencv-python-headless替代opencv-python：Vercel服务器无GUI环境，headless版本体积更小，完全满足手势识别需求。修改requirements.txt：

  flask
  opencv-python-headless
  cvzone
  

• 检查requirements.txt，移除所有不必要的依赖，只保留项目运行必需的包。

3. 分离大资源与核心代码 #

• 如果项目包含大体积静态资源（如模型文件、示例视频），将这些文件迁移到外部存储，代码中通过网络请求加载，不要打包进部署包。
• 拆分前后端：前端页面单独部署，后端仅保留API逻辑，进一步缩小后端部署包的体积。

4. 配置Vercel部署规则 #

• 创建vercel.json文件，指定部署时的文件包含/排除规则，确保只上传必要代码：

  {
    "functions": {
      "api/*.py": {
        "runtime": "@vercel/python@3.10"
      }
    },
    "includes": ["api/**/*", "templates/**/*", "static/**/*"],
    "excludes": ["venv/**", "__pycache__/**", ".git/**"]
  }
  

• 进入Vercel项目设置，确认部署配置中没有包含大文件目录。

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