本文详解 django 项目在 vercel 平台部署时的关键配置要点，重点解决因 runtime 字段值错误导致的函数运行时加载失败问题，并提供可直接使用的 vercel.json 配置、静态文件处理方案及部署注意事项。
本文详解 django 项目在 vercel 平台部署时的关键配置要点，重点解决因 runtime 字段值错误导致的函数运行时加载失败问题，并提供可直接使用的 vercel.json 配置、静态文件处理方案及部署注意事项。
Vercel 原生支持 Python 函数运行时，但不支持直接使用模糊或不存在的 runtime 名称（如 "vercel-python"）。其底层机制是通过 npm 包名精确匹配官方 Python 运行时——即必须指定形如 @vercel/python@X.Y.Z 的完整语义化版本标识。若 runtime 字段填写错误（例如拼写错误、省略版本号或使用未发布的包名），Vercel 构建阶段将报错：
Error: Function Runtimes must have a valid version, for example [@vercel/python@4.5.0]
✅ 正确做法是：前往 npm @vercel/python 页面 查看最新稳定版（截至 2024 年推荐使用 @vercel/python@4.6.0 或更高兼容 Django 4.x/5.x 的版本），并在 vercel.json 中严格声明。
提供使用 django-unfold (v0.56+) 构建高级 Django 管理界面的专业指导。当用户提及 django-unfold、unfold admin 等内容时使用此技能。
以下是经过验证的最小可用 vercel.json 配置示例：
{
"version": 2,
"functions": {
"core/wsgi.py": {
"runtime": "@vercel/python@4.6.0"
},
"build_files.sh": {
"runtime": "@vercel/static-build"
}
},
"routes": [
{
"src": "/static/(.*)",
"dest": "/static/$1"
},
{
"src": "/(.*)",
"dest": "core/wsgi.py"
}
]
}⚠️ 关键注意事项：
- 路径一致性：确保 core/wsgi.py 是实际存在的 WSGI 入口文件路径（通常位于 Django 项目根目录下的 core/ 子应用中），且该文件导出符合 PEP 3333 规范的 application 可调用对象；
- 依赖管理：Vercel 会自动识别并安装项目根目录下的 requirements.txt，请确保其中包含 django、gunicorn（推荐）或 uvicorn（需额外适配）等必要依赖；
-
静态文件：Django 的 collectstatic 必须在构建阶段完成。建议在 build_files.sh 中执行（示例）：
# build_files.sh python manage.py collectstatic --noinput
- 环境变量：敏感配置（如 SECRET_KEY、DEBUG=False、数据库 URL）需在 Vercel 项目设置 → Environment Variables 中手动添加，不可硬编码在代码中；
- 调试建议：本地可通过 vercel dev 模拟部署环境，快速验证路由与 WSGI 加载逻辑。
总结：Vercel 部署 Django 的核心在于「精准 runtime + 正确入口 + 静态资源分离」。避开自定义运行时陷阱，严格遵循官方 Python 运行时规范，即可实现轻量、可靠、自动化的全栈部署。
