Vercel CLI 微前端(Microfrontends)完整实战指南:用 `vercel mf` 拆分、编排与本地联调多应用
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 与示例输出,可直接阅读仓库源码:
- 命令与 flag 定义:packages/cli/src/commands/microfrontends/command.ts
- 子命令分派入口:packages/cli/src/commands/microfrontends/index.ts
- 数据模型:packages/cli/src/commands/microfrontends/types.ts
- 校验与上下文工具:packages/cli/src/commands/microfrontends/utils.ts
- 各子命令实现:create-group.ts、add-to-group.ts、remove-from-group.ts、delete-group.ts、inspect-group.ts、pull.ts
- 单元测试:packages/cli/test/unit/commands/microfrontends/
本文所有行为描述均以当前仓库
packages/cli源码与skills/vercel-cli/references/microfrontends.md文档为准;计费与配额相关数字来自源码常量与输出文案,实际额度以 Vercel 服务端返回为准。