SuperAPI AI 工具集

vercel-services

编程与开发

查看项目

更新于 10-16 07:28

技能介绍

用途:Vercel Services 让你在单个 Vercel 项目内部署多个独立构建的单元,典型场景是把不同运行时(如 Python + JavaScript)合并到一次部署中,共享路由与环境变量;也适用于同运行时的多服务、不同框架或混合组合。该技能聚焦项目结构与配置,实际部署请参考 deployments-cicd 技能。

主要能力:每个服务是独立构建单元,部署到同一域名下的唯一子路径。构建时 Vercel 分别构建各服务;请求时按 URL 路径前缀路由(最长前缀优先)。通过 vercel.json 的 experimentalServices 字段启用。vercel dev -L 可自动检测框架并在本地把全部服务作为一个应用运行,-L(即 --local)无需登录 Vercel Cloud。仅根目录放 vercel.json,各服务独立管理依赖。

配置:在 vercel.json 中定义服务,例如 web 的 entrypoint 为 apps/web、routePrefix 为 /,api 的 entrypoint 为 backend/main.py、routePrefix 为 /server。项目 Framework Preset 必须在 Vercel 面板设为 Services。字段:entrypoint(必填,入口文件或目录路径)、routePrefix(必填,路由前缀)、framework(可选,框架标识,未设则自动检测)、memory(可选,最大内存 MB,128–10240)、maxDuration(可选,超时秒数,1–900)、includeFiles/excludeFiles(可选,glob 模式)。不要添加未知字段,否则构建失败。

运行时:Services 处于 beta。Python 与 Go 已测试并可用于生产,其他运行时可能可用但尚未验证。Python 支持 FastAPI、Flask、Django 或任意 ASGI/WSGI 应用,框架自动检测,entrypoint 指向应用文件,依赖放在服务目录的 pyproject.toml。Go 的 entrypoint 指向服务目录而非文件,且必须显式设置 "framework": "go",依赖放在服务目录的 go.mod。Node.js、Bun、Rust、Ruby、Wasm、Edge 理论上可用但未验证。

路由:Vercel 按前缀从长到短匹配,主服务(/)作为兜底。Vercel 自动在 routePrefix 挂载服务,因此服务处理器不应在路由中包含该前缀。挂载在子路径(非 /)的前端框架需配置自身 base path(如 next.config.js 的 basePath)与 routePrefix 一致。

环境变量:Vercel 自动生成 URL 变量。{SERVICENAME}URL(如 https://your-deploy.vercel.app/svc/api)用于服务端,供服务间请求;NEXT_PUBLIC{SERVICENAME}_URL(如 /svc/api)用于客户端浏览器请求(相对路径,无 CORS)。SERVICENAME 为 experimentalServices 中的键名大写;若项目设置中定义了同名变量,以你的值为准。

用法:参考 references/fastapi-vite/ 的标准布局,并按用户所选运行时调整。定义服务路由时不要带 routePrefix,Vercel 转发前会剥离前缀。校验 vercel.json 中每个服务都有 entrypoint 与 routePrefix;仅在自动检测失败时设置 framework(Go 必须设置)。脚手架完成后向用户展示文件结构,部署后展示部署 URL。

限制与排错:部署后路由 404 通常是未设 Services 框架预设,需在 Project Settings → Build & Deployment → Framework Preset 选择 Services 并重新部署。路由异常时检查 vercel dev 日志确认所有服务被识别,必要时显式设置 framework;验证前缀行为(处理器声明不带前缀的路由如 /health,其他服务请求用完整前缀如 /api/health);子路径前端需确认 base path 与 routePrefix 匹配。其他运行时尚未验证,未知字段会导致构建失败。