illegalCreed

中文

English

中文

English

Appearance

参考 ​

基于 single-spa v6 · 核于 2026-07

速查 ​

  • 本页汇总六张表：三种模块类型 / 生命周期状态机 / registerApplication 参数 / import maps 工作流 / 框架适配器 / 版本状态
  • 三类型一句话：application 靠路由（声明式、single-spa 托管）、parcel 靠手动（命令式、跨框架 UI）、utility module 靠 import（纯逻辑、无生命周期）
  • 生命周期一句话：bootstrap/mount/unmount（+ parcel update）各返回 Promise，走 NOT_LOADED → … → MOUNTED 状态机；LOAD_ERROR 可重试、SKIP_BECAUSE_BROKEN 永久隔离
  • registerApplication 一句话：name + app（加载函数/对象）+ activeWhen（前缀/含参/函数/数组）+ customProps（对象/函数）；start() 不调用就不挂载
  • import maps 一句话：原生 ESM + import maps（Baseline 2023-03）现代首选，SystemJS 历史 polyfill；共享依赖走 externals + import map；overrides 本地覆盖、deployer 并发部署
  • 适配器一句话：single-spa-vue（createApp/Vue）、single-spa-react（ReactDOMClient/ReactDOM + rootComponent）、single-spa-angular（singleSpaAngular + ng add）都返回 { bootstrap, mount, unmount }
  • 版本一句话：v6.0.3（2024-09）稳定 latest，v7 长期 beta（beta.13 停在 2025-09-22 后无更新）——生产用 v6
  • 定位一句话：single-spa 只编排、不隔离，是 qiankun 的底座（qiankun ≈ single-spa + HTML entry + 沙箱 + 样式隔离）

一、三种模块类型对比表 ​

维度application（应用）parcel（包裹）utility module（工具模块）
API 风格声明式 registerApplication命令式 mountRootParcel/mountParcel普通 ES 模块 export
激活方式按路由（activity function）手动调用 mount被 import 时
生命周期single-spa 自动托管你手动管理（须手动 unmount）无
额外生命周期—可选 update（推新 props 不重挂）—
是否渲染 UI是（必须）是（必须）通常否
框架无关是是（核心卖点）是（纯逻辑）
主要用途微前端主组织单位跨框架共享一块 UI共享逻辑（鉴权/请求/通知/样式库/错误追踪）
典型坏法该拆路由却塞进一个巨应用父组件卸载忘了手动 unmount → 泄漏演化成全局 store

详见三种模块类型。

二、生命周期状态机表 ​

状态含义下一步
NOT_LOADED已注册，未加载源码命中路由 → 加载
LOADING_SOURCE_CODE正在下载/执行源码成功 → NOT_BOOTSTRAPPED；失败 → LOAD_ERROR
NOT_BOOTSTRAPPED源码就绪，未 bootstrap→ BOOTSTRAPPING
BOOTSTRAPPINGbootstrap 执行中完成 → NOT_MOUNTED
NOT_MOUNTED已引导，未挂载（或刚卸载）激活 → MOUNTING
MOUNTINGmount 执行中完成 → MOUNTED
MOUNTED正活在 DOM 上停用 → UNMOUNTING
UPDATINGparcel 的 update 执行中完成 → MOUNTED
UNMOUNTINGunmount 执行中完成 → NOT_MOUNTED
UNLOADINGunloadApplication 卸载中完成 → NOT_LOADED（可重新引导）
LOAD_ERROR加载失败下次路由变化重试
SKIP_BECAUSE_BROKEN生命周期抛错/超时死亡永久跳过、不再尝试

超时配置：setBootstrapMaxTime / setMountMaxTime / setUnmountMaxTime / setUnloadMaxTime，参数 (millis, dieOnTimeout, warningMillis)；dieOnTimeout: true 超时 → SKIP_BECAUSE_BROKEN。错误处理：addErrorHandler(fn)（error 带 appOrParcelName）/ removeErrorHandler(fn)。重置：unloadApplication(name, { waitForUnmount }) 打回 NOT_LOADED；unregisterApplication(name) 彻底注销。查询：getAppStatus / getMountedApps / getAppNames。详见生命周期协议。

三、registerApplication 参数表 ​

参数类型说明
namestring应用唯一名，约定与 import map 键一致
app函数 / 对象加载函数 () => import(...)，或已解析对象 { bootstrap, mount, unmount }
activeWhen字符串 / 函数 / 数组何时激活（见下）
customProps对象 / 函数透传给生命周期的自定义数据；函数形态 (name, location) => ({...})

activeWhen 四种写法：

写法例匹配
路径前缀"/app1"/app1 及 /app1/**
含参路径"/users/:userId/profile"动态段匹配
activity function(loc) => loc.pathname.startsWith("/app2")完全自定义（须纯函数）
数组["/pathname/#/hash", "/app1"]命中其一即激活

start(opts)：不调用则应用只 load、不 mount；urlRerouteOnly（v6 默认 true）只在 URL 真正变化时 reroute。activity function 求值时机：hashchange/popstate、被劫持的 pushState/replaceState、triggerAppChange()、checkActivityFunctions()。容器约定：<div id="single-spa-application:应用名"></div>。详见 root config 与注册。

四、import maps 工作流表 ​

维度原生 ESM + import mapsSystemJS（历史 polyfill）
script 类型<script type="importmap"><script type="systemjs-importmap">
加载入口原生 importSystem.import(...)
构建产物格式标准 ESMSystem.register（webpack libraryTarget: "system" / rollup format: "system"）
浏览器支持Baseline Widely available（2023-03）老浏览器兼容层
吃标准 ESM 包✓✗（需 esm-bundle / JSPM CDN 取 System.register 版）
定位现代首选历史/兼容，退居 polyfill

共享依赖：构建时 externals: [/^@org\/.+/, "react"]（webpack）/ external（rollup）不打进 bundle，运行时 import map 指到唯一 URL → 全站共下一份。工具：import-map-overrides（本地只起一个应用、覆盖存 localStorage）、import-map-deployer（CI curl -X PATCH 并发安全改键）、systemjs-webpack-interop（动态 publicPath）。依赖 URL 来源：esm-bundle、JSPM CDN（system-cdn.jspm.io/npm:react@17.0.0/...）、generator.jspm.io、self-hosted。详见 import maps 工作流。

五、框架适配器表 ​

适配器关键必填参数要点
single-spa-vueVue 3：createApp + appOptions；Vue 2：Vue + appOptions可选 handleInstance(app, props)；single-spa props 挂在组件 this 上
single-spa-reactReact + rootComponent + ReactDOMClient（18+）/ ReactDOM（≤17）React 18 renderType 默认 createRoot；可配 errorBoundary(err, info, props)
single-spa-angularbootstrapFunction + template（+ Router/NgZone/NavigationStart）ng add single-spa-angular 生成 main.single-spa.ts 等
其他—svelte / preact / ember / angularjs / alpinejs / riot / inferno / dojo / backbone / cycle / html / web-components

配套工具：create-single-spa（脚手架）、single-spa-layout（声明式布局）、import-map-overrides、import-map-deployer。旁路：Angular 生态的 @angular-architects Native Federation 用原生 ESM + import maps 走 MF 心智，与 single-spa-angular 是两条独立路线。详见框架适配器。

六、版本状态表 ​

版本发布时间标签状态
6.0.02023-12-03—v6 首发
6.0.32024-09-29latest当前稳定版（生产推荐）
7.0.0-beta.02024-09-30betav7 beta 起点
7.0.0-beta.132025-09-22beta最新 beta，此后无更新
4.4.4—4.x老版本兼容标签

结论：生产用 v6.0.3；v7 长期 beta 且 2025-09 后停更，无需等待。single-spa 定位极窄（只编排），核心稳定、少变；它是 qiankun 的底座（qiankun ≈ single-spa + HTML entry + 沙箱 + 样式隔离）。详见现状与定位。

权威链接 ​

相关页 ​