Agent Skills
返回列表
🔒

Vercel 多服务一体部署

IT 运维与安全 更新于 2026.08.30

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/vercel-vercel-plugin-vercel-services。

技能介绍

要解决什么问题

一个应用往往同时有前端构建产物和独立后端(FastAPI、自定义 Node 服务等),你希望它们同一次部署、同一套 Preview,避免线上前后端版本错位,又不想让团队各自维护多个 Vercel 项目。Vercel 的 Services 模型就是在单个项目里声明多个服务根目录:各服务独立 build,但发布时原子地打成一个 deployment。

技能覆盖的核心能力

  • 选型对照:何时用 Services、何时用单框架项目(如 Next.js Route Handlers)、何时拆成多项目、何时用 Microfrontends。
  • vercel.json 分层:顶层负责对外 rewrites/redirects/headers;各 service 持有 buildCommand、framework、outputDirectory 等;无顶层 rewrite 匹配的服务为私有,仅能通过 bindings 访问。
  • 公网路由:顶层 rewrite 按顺序匹配,命中后由该服务终结处理(404 不会落到下一条规则)。按前端类型划分 URL:/api 全交后端,或 Next.js 只把 /api/v1/(.*) 等子路径转给后端;注意 Vercel 保留原始 path,后端需 root_path 或服务内 rewrite 处理前缀。
  • SPA 深链:静态前端服务需 service-scoped catch-all 到 index.html。
  • 子域:host 匹配可把 API 放到 api.example.com;Preview 只有单一主机名,需保留子路径 rewrite 并用 NEXT_PUBLIC_API_URL=/api 等相对地址。
  • Bindings:在调用方声明 binding,运行时注入 URL;不走公网 CDN/Firewall;不等于鉴权,需在应用层校验调用方。Go/Rust 原生 runtime 暂不能消费 bindings,需用 container 构建调用方。
  • 本地与排错:vercel dev 注入本地 binding;常见项包括 rewrite 顺序、后端 404 前缀、binding 仅在 runtime 可读等。

适用边界

Services 的代价是每次部署都会带上全部服务——只有当你明确需要单独回滚某一个服务时,才应考虑拆项目。不要为了把单一框架拆成多个进程而引入 Services;应存在独立的运行时、框架、依赖或所有权理由。destination.path 在 schema 中存在但请求时不生效,改路径请用服务内 rewrite 或 routes 里的 path 变换。

使用场景

  • Next.js 前端与 FastAPI 后端同属一个 Vercel 项目,需要把 `/api/users` 等路径稳定转到后端且 Preview 与生产一致
  • Vite/CRA 静态前端把整段 `/api` 交给 Node 或 Python 服务,同时要修复刷新深链时的 404
  • 生产环境用 `api.example.com` 暴露后端,Preview 仍只靠子路径访问同一 API 服务
  • 前端 Serverless Function 要通过 binding 调用未配置公网 rewrite 的私有后端,避免硬编码部署域名

适合人员

  • 全栈工程师在同一仓库维护前后端,需要原子发布与可回滚的一体化 Vercel 配置
  • 平台或 DevOps 工程师负责 `vercel.json` 顶层 rewrite 顺序、子域与私有服务暴露策略
  • 后端维护者接在 Vercel Services 后收到带完整前缀的路径,需要对照 FastAPI `root_path` 或服务内 rewrite 改路由
  • Node/Python 服务作者要在 runtime 读取 binding 变量做服务间调用,并区分公网 rewrite 与仅内网可达