1. 项目概述为什么选择Vercel托管Python后端如果你正在开发一个Python后端API比如一个简单的数据查询接口、一个机器学习模型的推理服务或者一个为你的小程序提供数据的后端那么部署上线往往是项目从“玩具”走向“服务”的关键一步。传统上我们可能会想到租用云服务器然后配置Nginx、Gunicorn再处理SSL证书和防火墙一套流程下来半天时间就没了而且后续的运维、监控、扩展都是头疼事。最近几年Serverless无服务器架构的兴起让部署后端API变得前所未有的简单。Vercel这个以托管前端项目尤其是Next.js而闻名的平台其实对Python后端API的支持也相当出色。它最大的吸引力在于零配置部署、自动HTTPS、全球CDN加速以及最重要的——免费额度足够个人项目和小型应用折腾。你只需要把代码推送到Git仓库GitHub, GitLab, BitbucketVercel就能自动识别你的Python项目安装依赖并启动你的API服务。听起来很美好对吧但实际操作中很多朋友会卡在“环境依赖”这一步。Vercel的Serverless环境是“无状态”的每次请求都可能是一个全新的、临时的容器。这意味着你不能像在本地或自己的服务器上那样随意pip install一些包就完事了。你必须通过一个标准的requirements.txt文件来明确声明所有依赖并且要确保这些依赖与Vercel提供的Python运行时环境兼容。这篇文章我就以一个真实的Python Flask API项目为例带你走一遍从本地开发到成功部署到Vercel的全过程。我会重点拆解“引包引环境”这个核心难题分享我踩过的坑和总结的实用技巧确保你也能一次部署成功。2. 核心思路与项目结构设计在动手写代码之前我们先要理解Vercel运行Python项目的逻辑这决定了我们的项目结构应该如何设计。2.1 Vercel的Python运行时工作原理Vercel本质上将你的API部署为一个个Serverless Function无服务器函数。当你访问你的API地址时Vercel会启动一个包含你代码和依赖的临时环境来执行对应的函数处理完请求后环境可能会被销毁。因此你的代码必须是一个可以被“调用”的入口。对于PythonVercel官方支持将符合WSGIWeb Server Gateway Interface或ASGIAsynchronous Server Gateway Interface规范的应用作为入口。最常见的WSGI应用框架就是Flask和Django而FastAPI则是ASGI框架的代表。我们的核心任务就是创建一个符合规范的入口文件通常是api/index.py或根目录的app.py并确保Vercel在构建时能正确安装所有依赖。2.2 推荐的项目结构一个清晰的项目结构能避免很多部署时的诡异问题。下面是我推荐的结构适用于大多数中小型Python API项目my-python-api/ ├── api/ │ └── index.py # Vercel Serverless Function 入口文件 ├── requirements.txt # Python依赖清单核心 ├── vercel.json # Vercel项目配置文件可选但推荐 └── 其他项目文件如 utils/, models/ 等关键点解析api/index.py这是Vercel的默认约定。任何放在api目录下的.py文件都会被Vercel视为一个独立的Serverless Function。访问路径就是/文件名。例如api/index.py对应的API地址就是https://your-project.vercel.app/api。api/hello.py对应的地址就是https://your-project.vercel.app/api/hello。这种结构非常适合构建由多个独立函数组成的API。requirements.txt这是Python项目的“身份证”。Vercel的构建系统在部署时会读取这个文件并使用pip install -r requirements.txt命令在它的云端环境中安装所有依赖。这个文件的内容和格式至关重要。vercel.json这个配置文件允许你自定义构建命令、输出目录、路由规则等。对于纯Python API我们通常用它来指定使用哪个Python版本或者重写一些默认行为。注意你也可以使用根目录的app.py作为入口但这需要在vercel.json中进行额外配置告诉Vercel你的应用对象在哪里。对于新手我强烈建议先从api/index.py这种标准结构开始它能让你更直观地理解Vercel的函数模型。3. 手把手实操从零构建并部署一个Flask API理论说再多不如动手做一遍。我们一起来创建一个简单的“待办事项Todo”API它支持获取列表和添加新事项。3.1 第一步初始化本地项目与环境首先在你的本地电脑上创建一个新目录并初始化一个干净的Python虚拟环境。虚拟环境能隔离项目依赖是Python开发的最佳实践。# 创建项目目录 mkdir vercel-python-todo-api cd vercel-python-todo-api # 创建虚拟环境假设你使用Python3 python3 -m venv venv # 激活虚拟环境 # 在 macOS/Linux 上 source venv/bin/activate # 在 Windows 上 # venv\Scripts\activate # 激活后命令行提示符前通常会显示 (venv)3.2 第二步编写核心API代码现在创建api目录和入口文件index.py。# api/index.py from flask import Flask, jsonify, request from flask_cors import CORS # 处理跨域请求如果前端需要调用的话 app Flask(__name__) CORS(app) # 允许所有域的跨域请求生产环境建议配置具体域名 # 用一个内存列表模拟数据库 todos [ {id: 1, task: 学习Vercel部署, completed: False}, {id: 2, task: 写一篇技术博客, completed: True}, ] app.route(/api, methods[GET]) def get_todos(): 获取所有待办事项 return jsonify({success: True, data: todos}) app.route(/api, methods[POST]) def add_todo(): 添加一个新的待办事项 data request.get_json() if not data or task not in data: return jsonify({success: False, error: 缺少任务内容}), 400 new_id max([todo[id] for todo in todos], default0) 1 new_todo { id: new_id, task: data[task], completed: data.get(completed, False) } todos.append(new_todo) return jsonify({success: True, data: new_todo}), 201 # 这个入口点是为了兼容Vercel的无服务器函数格式 # Vercel会寻找名为 app 或 application 的WSGI/ASGI应用对象 # 对于Flask直接导出 app 即可。 app app代码要点说明我们创建了一个Flask应用并定义了两个端点GET /api和POST /api。使用内存列表todos来存储数据。注意在真实的Serverless环境中由于函数实例是无状态的内存数据在请求结束后就会丢失且不同请求可能由不同实例处理因此绝对不能用内存做持久化存储。这里仅作演示真实项目需要连接数据库如Vercel Postgres、Supabase或外部数据库。最后一行app app看起来有点多余但这是为了明确导出一个名为app的对象这是Vercel识别WSGI应用的常见方式之一。你也可以写application app。3.3 第三步创建并管理requirements.txt核心环节这是整个部署过程中最容易出错的一步。我们需要生成一个精确的依赖列表。首先在虚拟环境中安装项目所需的包pip install flask flask-cors安装完成后使用pip freeze命令生成依赖列表。但直接使用pip freeze requirements.txt可能会引入很多不必要的、来自你本地全局环境的依赖导致文件臃肿且可能冲突。更推荐的做法是仅记录你主动安装的核心包及其版本范围。手动创建一个requirements.txt文件# requirements.txt Flask2.3.0,3.0.0 Werkzeug2.3.0,3.0.0 flask-cors4.0.0,5.0.0为什么这么做精确控制pip freeze会列出所有包包括pip、setuptools等底层工具这些在Vercel的构建环境中可能已经存在或版本不同强行指定可能导致冲突。版本范围使用和指定一个兼容的版本范围比固定死一个具体版本如Flask2.3.2更灵活。这既能保证核心功能又能让Vercel的包解析器在一定范围内选择最兼容的版本提高部署成功率。简洁明了只列出你的代码直接导入的包Flask,flask-cors及其直接依赖Werkzeug是Flask的核心依赖。这通常就够了。实操心得我遇到过无数次部署失败都是因为requirements.txt里包含了不兼容的包版本。一个黄金法则是在本地开发时尽量使用与Vercel官方支持的Python版本相近的环境。你可以在Vercel项目设置的“Build Development Settings”中查看支持的版本如Python 3.9 3.10 3.11。在本地使用pyenv或conda创建对应版本的虚拟环境能极大减少环境差异。3.4 第四步配置vercel.json可选但推荐虽然Vercel能自动检测Python项目但显式配置可以避免歧义尤其是当项目根目录还有其他文件时。在项目根目录创建vercel.json{ functions: { api/*.py: { runtime: python3.11 } }, builds: [ { src: api/*.py, use: vercel/python } ], routes: [ { src: /(.*), dest: /api } ] }配置解析functions: 指定api目录下的所有.py文件都使用Python 3.11运行时。你可以根据需要改为3.9或3.10。builds: 告诉Vercel对于api目录下的Python文件使用官方的Python构建器vercel/python。routes: 这是一个重写规则。它将所有发送到根路径/的请求都重定向到/api这个函数。这样你访问https://your-project.vercel.app/就相当于访问https://your-project.vercel.app/api。如果你有多个函数如api/index.py,api/hello.py这个规则可能不需要或者需要更复杂的配置。3.5 第五步本地测试与调试在部署前务必在本地测试API是否能正常运行。本地运行Flask应用# 确保在项目根目录且虚拟环境已激活 export FLASK_APPapi/index.py # macOS/Linux # 在Windows CMD中set FLASK_APPapi\index.py # 在Windows PowerShell中$env:FLASK_APP api\index.py flask run访问http://127.0.0.1:5000/api你应该能看到JSON格式的待办事项列表。使用vercel dev进行仿真测试强烈推荐 Vercel CLI提供了一个本地开发服务器能模拟真实的Vercel生产环境。# 全局安装Vercel CLI npm i -g vercel # 在项目根目录登录会打开浏览器 vercel login # 在项目根目录链接项目选择“Link to existing project”或创建新项目 vercel link # 启动本地仿真服务器 vercel dev访问http://localhost:3000/api。这个环境会读取你的vercel.json配置并使用与线上更接近的构建流程是排查部署问题的最佳工具。3.6 第六步部署到Vercel确保代码已经提交到Git仓库如GitHub。这是最推荐的部署方式。通过Vercel网站部署访问 vercel.com 用GitHub账号登录。点击“Add New...” - “Project”。导入你的GitHub仓库。Vercel会自动检测为Python项目。检查配置根目录、构建命令等通常无需修改。点击“Deploy”。等待几分钟构建和部署就完成了。通过Vercel CLI部署# 在项目根目录执行 vercel --prod按照提示操作即可。部署成功后你会获得一个类似https://your-project.vercel.app的URL。访问https://your-project.vercel.app/api即可测试你的线上API。4. 深度解析requirements.txt的陷阱与高级技巧requirements.txt是部署成败的关键。下面我展开讲讲这里面的门道和高级用法。4.1 依赖冲突与版本锁定Python的包依赖有时像一团乱麻。包A依赖包B的1.0版本包C依赖包B的2.0版本这就产生了冲突。在本地pip可能会通过复杂的解析找到一个可行解但Vercel的构建环境可能不同。策略一使用pip-tools进行精确编译pip-tools提供了pip-compile命令可以根据一个顶层的requirements.in文件生成一个锁定所有次级依赖版本的requirements.txt。# 安装 pip-tools pip install pip-tools # 创建 requirements.in只写你直接需要的包 # requirements.in 内容 Flask flask-cors # 编译生成 requirements.txt pip-compile requirements.in --output-filerequirements.txt生成的requirements.txt会包含所有依赖及其精确版本如Flask2.3.2Werkzeug2.3.6。这能保证环境的一致性。但缺点是如果某个次级依赖更新了不兼容的版本你可能需要手动干预或定期重新编译。策略二在Vercel上使用Python版本和构建命令如果遇到棘手的依赖冲突可以在Vercel项目设置的“Build Development Settings”中尝试切换Python版本如从3.11降到3.9。在“Build Command”中覆盖默认行为例如pip install --upgrade pip setuptools wheel pip install -r requirements.txt先升级打包工具有时能解决一些古老的包安装问题。4.2 处理二进制依赖与系统库有些Python包如psycopg2PostgreSQL驱动、Pillow图像处理、cryptography依赖系统级别的C库。Vercel的构建环境基于Linux如果你的包需要编译通常没问题因为Vercel提供了编译工具链。但是你需要确保requirements.txt里的是这些包的纯Python轮子wheel或源码版本而不是预编译的、针对特定平台如macOS的版本。通常直接写包名如psycopg2-binary即可pip会在构建时自动获取适合Linux的版本进行编译或安装。一个常见错误在macOS上开发使用了某些包的macOS特定版本然后pip freeze到了requirements.txt里。部署到Vercel的Linux环境时就会失败。这就是为什么建议在requirements.in里只写顶级包名让pip-compile在部署时根据目标环境解析依赖。4.3 使用runtime.txt指定Python版本除了在vercel.json中指定你还可以在项目根目录创建一个runtime.txt文件来指定Python版本这是Heroku等平台的传统Vercel也支持。# runtime.txt python-3.11.0这比在vercel.json中指定更直观但注意两者如果同时存在Vercel可能会优先使用vercel.json中的配置。5. 进阶部署场景与优化5.1 部署FastAPIASGI应用FastAPI是当下非常流行的异步Python框架。部署到Vercel需要一点小改动因为Vercel的Python构建器默认寻找WSGI应用。api/index.py示例from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware app FastAPI() # 添加CORS中间件 app.add_middleware( CORSMiddleware, allow_origins[*], # 生产环境请替换为具体前端域名 allow_credentialsTrue, allow_methods[*], allow_headers[*], ) app.get(/api) async def read_root(): return {message: Hello from FastAPI on Vercel} # 关键为了兼容Vercel需要将ASGI应用包装成WSGI兼容的格式 # 但更简单的方式是使用 uvicorn 或 hypercorn 的ASGI适配器。 # 实际上Vercel的 vercel/python 构建器现在能自动检测ASGI应用。 # 你只需要确保导出的应用对象名是 app。 app app对于FastAPI依赖文件requirements.txt需要包含fastapi0.100.0,0.101.0 uvicorn[standard]0.23.0,0.24.0uvicorn是ASGI服务器Vercel在运行时会使用它来启动你的FastAPI应用。5.2 处理静态文件与大型依赖Serverless函数有执行时间和包大小的限制Vercel免费计划是10秒和50MB。如果你的API需要加载大型模型如机器学习模型需要注意将模型文件放在项目内模型文件会被打包进函数。确保总大小在限制内。使用外部存储更推荐的做法是将大型文件如模型.pkl文件存储在云存储如AWS S3、Google Cloud Storage或Vercel自家的Blob存储中。在函数启动时或首次请求时下载到临时目录。虽然这会增加冷启动时间但能避免包体积超标。利用层Layers或全局变量在多次调用间函数的容器可能被复用热启动。你可以将加载好的模型对象存储在全局变量中这样在热启动时就不需要重新加载。但这不是百分百可靠的要做好失败重试的逻辑。5.3 配置环境变量与密钥绝对不要将API密钥、数据库连接字符串等敏感信息硬编码在代码中Vercel提供了环境变量管理。在Vercel控制台设置进入项目设置 - Environment Variables。添加你的变量例如DATABASE_URL。在代码中读取import os database_url os.environ.get(DATABASE_URL) if not database_url: # 可以提供一个本地开发用的默认值 database_url sqlite:///local.db本地开发使用python-dotenv包。在项目根目录创建.env文件务必加入.gitignore内容如DATABASE_URLyour_local_db_url。在代码开头加载from dotenv import load_dotenv load_dotenv() # 这会读取 .env 文件中的变量到 os.environ6. 常见部署问题与排查实录即使按照教程操作你也可能会遇到一些问题。这里记录了几个我亲自踩过的坑和解决方法。6.1 构建失败ModuleNotFoundError或ImportError这是最常见的问题意味着Vercel构建环境没有成功安装你的某个依赖或者安装的版本/路径不对。排查步骤检查requirements.txt格式确保没有拼写错误版本号语法正确。每行一个包。查看构建日志在Vercel项目的“Deployments”页面点击失败的部署查看详细的构建日志。日志会显示pip install的过程。仔细看是否有红色的错误信息比如某个包编译失败、版本不兼容等。简化依赖如果依赖复杂尝试先只部署一个最简单的Flask应用只有Flask一个依赖。成功后再逐步添加其他包定位是哪个包引起的问题。检查Python版本兼容性有些较新或较旧的包可能不支持你指定的Python版本。尝试在vercel.json中切换Python版本如从3.11切到3.9。6.2 运行时错误502 BAD_GATEWAY或Function Invocation Error部署成功但访问API时返回5xx错误。排查步骤检查函数日志在Vercel项目的“Functions”标签页下找到对应的函数如api/index查看其运行时日志。这里会打印出Python应用的错误堆栈信息是调试的黄金线索。检查入口点确保api/index.py中导出的应用变量名是app或application。这是Vercel Python构建器的默认约定。检查路径你的代码里是否使用了绝对路径读写文件在Serverless环境中当前工作目录和文件系统权限可能与本地不同。尽量使用相对路径并做好异常处理。冷启动超时如果函数代码初始化如加载大模型时间超过Vercel的限制免费版10秒会导致函数超时并返回错误。优化初始化逻辑或考虑使用更快的启动方案如减小模型尺寸、使用外部存储按需加载。6.3 跨域CORS问题如果你的前端在your-frontend.com调用部署在Vercel上的APIyour-api.vercel.app浏览器会因同源策略而阻止请求。解决方案在Flask中使用flask-cors扩展如本文示例。在FastAPI中使用CORSMiddleware。生产环境注意不要使用allow_origins[*]而应该明确指定前端域名如allow_origins[https://your-frontend.com]这样更安全。6.4 如何连接数据库内存存储不可靠。你需要一个外部数据库。Vercel推荐使用其集成的Vercel Postgres或Vercel KV (Redis)。你也可以使用任何提供公开访问地址的数据库服务如Supabase, PlanetScale, MongoDB Atlas等。以连接Vercel Postgres为例在Vercel项目仪表板进入“Storage”标签页创建Postgres数据库。它会自动生成连接字符串并作为环境变量POSTGRES_URL添加到你的项目中。在代码中使用psycopg2或asyncpg等驱动连接。记得将psycopg2-binary添加到requirements.txt。一个重要的提醒Serverless函数会创建大量短暂的数据库连接。务必使用连接池或在每个函数调用内部创建并关闭连接避免耗尽数据库连接数。许多ORM如SQLAlchemy和驱动都支持连接池配置。部署Python API到Vercel核心在于理解其Serverless函数模型并妥善管理依赖和环境。从简单的Flask应用开始遵循api/index.py的结构精心维护requirements.txt利用好vercel dev进行本地仿真大部分问题都能迎刃而解。当你的API流量增长开始关心性能、冷启动和成本时再深入探索数据库连接优化、函数配置调优和监控告警那就是另一个阶段的旅程了。至少现在你已经拥有了一个免费、自动伸缩、全球可访问的API服务起点。