Vercel CLI 微前端(Microfrontends)完整实战指南:用 `vercel mf` 拆分、编排与本地联调多应用

原创2026-09-22 18:44:071,932 阅读
文章标签:CLI云原生Serverless构建工具DevOps后端前端边缘计算

Vercel CLI 微前端(Microfrontends)完整实战指南:用 vercel mf 拆分、编排与本地联调多应用

本篇技术指南围绕 Vercel CLI 的 microfrontends(别名 mf)命令族展开,讲解如何把大型应用拆分为多个可独立部署的子应用(child app),再通过一个默认应用(default app)统一编排路由、组合成对外一致的单一应用。读完本文,你将掌握用 vercel mf create-group / add-to-group / remove-from-group / delete-group / inspect-group / pull 管理微前端分组、用 microfrontends.json 声明路径路由、以及通过 microfrontends proxy 与 microfrontends port 完成 monorepo / polyrepo 本地联调的完整工作流,同时理解各命令背后的源码级行为与限制。

核心概念:默认应用与子应用的分工

Vercel Microfrontends 的目标是:把一个大型应用拆分成若干可独立部署的单元,这些单元最终渲染成一个连贯的完整应用。整个模型只有两个角色:

  • 默认应用(default app):承载并部署 microfrontends.json 配置文件,负责服务所有未匹配的请求(fallback)。配置文件的任何变更只有默认应用部署到生产环境后才会生效。
  • 子应用(child app):在 microfrontends.json 中通过 routing 声明自己负责的路径模式(path pattern),例如 /docs、/docs/*。子应用各自独立开发、独立部署。

这一分工可以从 CLI 源码中得到印证:packages/cli/src/commands/microfrontends/create-group.ts 在创建分组后,如果当前链接项目正是默认应用,会提示生成 microfrontends.json,其生成逻辑(generateMicrofrontendsConfig)为默认应用写入 development.fallback,为其余子应用写入 routing.paths:

{
  "$schema": "https://openapi.vercel.sh/microfrontends.json",
  "applications": {
    "web": {
      "development": {
        "fallback": "...your-production-domain.vercel.app"
      }
    },
    "docs": {
      "routing": [
        {
          "paths": ["/docs", "/docs/*"]
        }
      ]
    }
  }
}

路由路径支持 path-to-regexp 语法(如 /docs、/docs/*、/app/:slug),完整校验发生在部署阶段;CLI 侧只做前置的快速检查(详见后文「路径与路由校验规则」)。

快速开始:三行命令跑通主流程

vercel mf create-group    # create a group and add projects
vercel mf pull            # pull microfrontends.json for local dev
vercel mf proxy           # start the local dev proxy
  • vercel mf create-group:交互式创建分组并把项目加入分组;
  • vercel mf pull:把默认应用上的 microfrontends.json 拉到本地(polyrepo 场景必需);
  • vercel mf proxy:启动本地开发代理,把请求按配置路由到本地正在运行的应用。

命令别名在源码中定义于 packages/cli/src/commands/microfrontends/command.ts:microfrontendsCommand 的 aliases: <a href="https://link.gitcode.com/i/ec75ae846b6cfa4669c2e1c255695094" target="_blank">'mf'],因此 microfrontends 与 mf 完全等价;分派逻辑见 [packages/cli/src/commands/microfrontends/index.ts。

管理分组(Managing Groups)

分组(group)是微前端编排的顶层容器。源码中分组的数据结构定义在 packages/cli/src/commands/microfrontends/types.ts:一个分组包含 id、slug、name、可选的 fallbackEnvironment,以及一组项目(MicrofrontendsProject),每个项目可携带 isDefaultApp、enabled、defaultRoute 等微前端元信息。

创建分组:交互式与非交互式

vercel microfrontends create-group                   # interactive
vercel mf create-group --non-interactive \           # fully scripted
  --name "my-group" \
  --project web \
  --project docs \                                   # repeatable
  --default-app web \
  --default-route / \
  --project-default-route docs=/docs \               # required per non-default project
  --yes                                              # skip confirmation

各 flag 的官方定义(见 command.ts 中 createGroupSubcommand):

Flag 类型 说明
--name String 分组名称,非交互模式下必填
--project String[](可重复) 要加入分组的项目名,非交互模式下必填
--default-app String 默认应用的项目名;多项目时非交互模式下必填
--default-route String 默认应用的默认路由(默认 /)
--project-default-route String[](可重复) 格式为 <project>=<route>,如 docs=/docs;每个非默认项目在非交互模式下都必填
--yes Boolean 跳过创建确认

源码实现要点(create-group.ts):

  • 分组名有长度上限:MAX_GROUP_NAME_LENGTH = 48,超长、为空、与现有组重名都会在 validateGroupName 中报错。
  • 非交互模式严格校验:缺少 --name、缺少 --project、多项目却未指定 --default-app、非默认项目缺少 --project-default-route,都会直接报错退出(退出码 1)。
  • --project-default-route 解析:按第一个 = 切分项目标识与路由,项目必须是所选项目之一,且不能是默认应用(默认应用用 --default-route),否则报 Use --default-route for the default app "web". 之类的错误。
  • 一个项目只能属于一个分组:isProjectInMicrofrontendsGroup 会过滤掉已在其他分组中的项目。

⚠️ 重要限制:--non-interactive 在添加项目会超出免费额度时会被阻断——用户必须交互式确认账单变更。源码中该逻辑位于 create-group.ts 的 wouldAffectBilling 检查:当 existingMfeProjectCount + projectsToAddCount > freeProjects(免费项目数为 2)时,非交互模式会以 purchase_requires_user 状态拒绝执行并提示改用交互终端或 Dashboard,即使带 --yes 也不行(--yes 只能跳过确认,不能绕过账单阻断)。同理,add-to-group 也有完全相同的阻断逻辑。

创建成功后,若当前链接项目就是默认应用,CLI 会提示生成 microfrontends.json;否则会提示下一步需要把 microfrontends.json 加到默认应用。

查看分组:inspect-group

inspect-group 返回项目的名称、框架(framework)、Git 仓库与根目录等信息,非常适合用于自动化生成 microfrontends.json。

vercel mf inspect-group                              # interactive group selection
vercel mf inspect-group --group="my-group"           # specific group
vercel mf inspect-group --group="my-group" --format=json  # machine-readable

实现位于 inspect-group.ts,几点值得注意:

  • 除 --group 外还支持 --config-file-name(自定义微前端配置文件路径,必须以 .json 或 .jsonc 结尾)与 --format / --json 输出选项。
  • 非交互模式(无 TTY)下必须显式传 --group,否则会以 MISSING_ARGUMENTS 状态要求补全参数。
  • JSON 输出结构包含 group(id / slug / name / fallbackEnvironment)、projectCount、defaultApp、configFile(本地解析出的配置文件路径)、config(是否存在及 applications 列表)以及每个项目的 projects 数组;每个项目含 id、name、isDefaultApp、enabled、defaultRoute、productionDomain、framework、git(org / repo / rootDirectory)、packageName、inGroupConfig(是否仍被配置文件引用)等字段。
  • 它还会对比本地 Git 仓库与项目链接,尝试从 package.json 读取包名、从默认应用根目录解析 microfrontends.json / microfrontends.jsonc,方便在本地直接核对配置是否存在。

添加 / 移除项目

这两个命令必须从项目目录运行。

vercel mf add-to-group                               # interactive
vercel mf add-to-group --group="my-group" --default-route=/docs

vercel mf remove-from-group                          # interactive
vercel mf remove-from-group --yes                    # non-interactive: skips all confirmations

add-to-group 需要交互式终端;remove-from-group 传入 --yes 后可非交互运行,--yes 会跳过项目链接确认、"仍被 microfrontends.json 引用"的确认以及最终的移除确认。

源码层面的行为差异(add-to-group.ts 与 remove-from-group.ts):

  • add-to-group:先通过 ensureMicrofrontendsContext 完成项目链接并要求团队(org)环境(Microfrontends are only available for teams.);校验项目不在其他分组、分组存在且未达每分组项目上限;最终通过 PATCH /v10/projects/{id}/microfrontends 写入 { microfrontendsGroupId, isDefaultApp: false, defaultRoute, enabled: true }。默认路由会被用于部署截图与项目的默认链接。
  • remove-from-group:同样通过 PATCH /v10/projects/{id}/microfrontends 写入 { enabled: false } 完成移除。若分组配置(microfrontends.json)仍引用该项目,会给出警告——不更新配置会导致组内其他微前端项目在下次部署时失败。
  • 默认应用无法通过 CLI 移除:源码在 remove-from-group.ts 中显式检查 projectEntry?.microfrontends?.isDefaultApp 并报错。正确姿势是:先在 Vercel Dashboard 中更换默认应用,再对原默认项目执行 remove-from-group。
  • 权限:创建或修改微前端分组要求团队 Owner 角色,403 时 CLI 会明确提示 You must be an Owner to create or modify microfrontends groups.。

移除后,记得在默认应用的 microfrontends.json 中同步删除该项目条目,否则下一次默认应用部署时会产生路由错误。

删除分组:不可逆操作

vercel mf delete-group                               # interactive
vercel mf delete-group --group="my-group" --yes      # non-interactive

删除分组不可逆,分组内的所有项目会被自动移出(但不会删除项目本身)。实现细节(delete-group.ts):

  • 交互模式下要求手动输入分组名确认(Type my-group to confirm deletion:),输入不一致则中止;
  • 非交互模式必须同时提供 --group 与 --yes,否则以 CONFIRMATION_REQUIRED 状态拒绝执行;
  • 最终调用 DELETE /v2/teams/{teamId}/microfrontends/{groupId}。

pull:拉取微前端配置

vercel microfrontends pull
vercel mf pull --dpl <deployment-url>

pull 从默认应用下载 microfrontends.json,在多仓库(polyrepo)场景下是本地开发的必要前置步骤。需要 CLI 44.2.2+。

实现位于 pull.ts,关键行为:

  • 不带 --dpl 时,请求 /v1/microfrontends/projects/{projectId}/production-mfe-config 获取生产配置;带 --dpl 时改为请求 /v1/microfrontends/{dpl}/config,可针对特定部署拉取对应配置。
  • 拉取到的配置会剥离每个 application 的 projectId 字段(保留 $schema 与 applications),然后以 2 空格缩进写入 .vercel/microfrontends.json。
  • 通过 ensureLink 自动处理项目链接,--yes 可在非交互场景下跳过链接确认。

本地开发(Local Development)

本地代理(proxy)会把请求路由到正在运行的应用,未匹配的请求回落到生产环境。默认端口:3024。

Monorepo(Turborepo)

在 Turborepo 环境下,代理会通过 turbo 自动启动(要求 turbo ≥ 2.3.6 或 ≥ 2.4.2):

turbo run dev --filter=web

不使用 Turborepo

手动在 package.json 中声明两个脚本并同时运行:

{
  "scripts": {
    "dev": "next dev --port $(microfrontends port)",
    "proxy": "microfrontends proxy microfrontends.json --local-apps web"
  }
}

microfrontends proxy 读取 microfrontends.json 并按 --local-apps web 指定本地应用;microfrontends port 输出当前应用被自动分配的开发端口(基于应用名的确定性分配)。

Polyrepo(多仓库)

vercel mf pull                                       # fetch microfrontends.json
next dev --port $(microfrontends port)               # start your app
microfrontends proxy --local-apps your-app-name      # start proxy

如果不想执行 pull,也可以直接设置环境变量指向配置文件的本地路径:

export VC_MICROFRONTENDS_CONFIG=/path/to/microfrontends.json

microfrontends proxy 与 microfrontends port

microfrontends proxy [configPath] --local-apps web docs   # multiple local apps
microfrontends proxy --port 4001                          # override port
  • [configPath] 位置参数:本地 microfrontends.json 路径;
  • --local-apps:声明哪些应用在本地运行(可传多个),其余请求回落生产;
  • --port:覆盖默认端口 3024。
next dev --port $(microfrontends port)

microfrontends port 根据应用名确定性地计算开发端口,保证每次本地启动端口一致,适合直接内嵌到 dev 脚本中。

部署(Deployment)

每个应用独立部署。路由行为完全由默认应用携带的 microfrontends.json 决定——配置变更只有默认应用部署到生产环境后才会生效。因此:

  • 修改路由路径 → 需要重新部署默认应用;
  • 只部署子应用 → 不会应用任何 microfrontends.json 的变更。

这也是创建分组后 CLI 提示「先为默认应用生成 microfrontends.json、再创建预览部署验证、最后发布生产」的原因。

路径与路由校验规则

CLI 内置了两层前置校验(完整实现见 utils.ts),可以在交互输入和 flag 解析时尽早拦截明显错误:

  • validateDefaultRoute(path)(用于 --default-route 与 --project-default-route):
    • 必须以 / 开头(Route must start with /);
    • 不得包含空白字符(Route must not contain spaces);
    • 不得包含 ? 或 #(查询串与片段不被允许);
    • 必须是合法 URL 路径(通过 new URL(path, 'http://n') 验证)。
  • validateRoutingPath(path)(用于 microfrontends.json 中的 routing.paths):
    • 必须以 / 开头;
    • 不得包含空白字符;
    • 支持 path-to-regexp 语法,如 /docs、/docs/*、/app/:slug;完整校验发生在部署阶段,此函数只做快速前置检查。

创建分组时交互式填写各子应用路径的提示为「逗号分隔,例如 /docs, /docs/*」(见 create-group.ts 的路径输入逻辑)。

反模式清单(Anti-Patterns)

以下行为应坚决避免,均与本文前述的 CLI 强制行为一一对应:

  • 在超出免费额度时使用 --non-interactive:CLI 会直接阻断(purchase_requires_user),请改为交互式运行。
  • Polyrepo 场景跳过 vercel mf pull:本地没有 microfrontends.json,代理无法正确路由请求。
  • remove-from-group 后忘记更新 microfrontends.json:残留条目会在默认应用下次部署时引发路由错误。
  • 在 CI 中运行 add-to-group:它要求交互式终端——请改用 Vercel Dashboard。remove-from-group 和 delete-group 都接受 --yes,可以非交互运行。
  • 尝试移除默认应用:CLI 明确拒绝。先在 Dashboard 更换默认应用,再移除原默认项目。
  • 配置变更后只部署子应用:microfrontends.json 的变更只有默认应用部署后才会生效。

补充:配额、计费与权限边界

从源码可以确认的几项硬性边界(以当前仓库代码为准):

  • 仅团队可用:Microfrontends are only available for teams.(个人空间不可用),见 utils.ts 的 ensureMicrofrontendsContext 与 create-group.ts。
  • 免费额度:每团队前 2 个微前端项目免费(源码中 const freeProjects = 2);超出部分按每项目 $250.00/月计费,另加 $2.00/百万次微前端路由请求费。计费明细会在创建/添加项目前完整打印。
  • 配额上限:每个团队的分组数上限(maxMicrofrontendsGroupsPerTeam)与每个分组的项目数上限(maxMicrofrontendsPerGroup)由服务端接口 /v1/microfrontends/groups 返回,CLI 严格校验。
  • 权限:创建/修改/删除分组要求团队 Owner(403 拦截)。

如需进一步了解各子命令的精确 flag 与示例输出,可直接阅读仓库源码:

本文所有行为描述均以当前仓库 packages/cli 源码与 skills/vercel-cli/references/microfrontends.md 文档为准;计费与配额相关数字来自源码常量与输出文案,实际额度以 Vercel 服务端返回为准。

登录后查看全文
vercel