前端微前端【免费下载链接】qiankun Blazing fast, simple and complete solution for micro frontends.项目地址https://gitcode.com/gh_mirrors/qi/qiankun点击查看免费下载本文是 qiankun 微前端框架的快速上手指南基于官方 快速上手文档讲解如何借助官方 Agent skill 创建并运行一个 React TypeScript 主应用端口 7099和一个微应用端口 7101并深入剖析主应用通过loadMicroApp管理微应用实例的完整机制。读完本文你将能够独立完成一个可运行、可卸载、可独立开发的 qiankun 微前端最小工程并理解name、entry、container三个核心字段与微应用生命周期契约背后的源码级原理。开始前的前置条件在动手之前请先确认你的环境满足以下要求Node.js20.19与 npmqiankun 3.x 的构建工具链Vite 等依赖此版本基于 Chromium 的浏览器Chrome、Edge 等或 Safari完整浏览器支持要求见浏览器支持两个空闲端口按官方约定主应用固定使用7099微应用从7101开始编号。[!WARNING]Firefox 与 ESM 应用qiankun 的 ESM 沙箱依赖动态注入 import map而 Firefox 目前还不支持这项能力。因此本指南的验证环节请使用基于 Chromium 的浏览器Chrome、Edge 等或 Safari 完成。Classic 模式非 ESM的微应用不受此限制。第一步安装官方 Agent skill 并生成项目qiankun 以 Agent Skills。安装后Claude Code、Cursor 等 agent 可以按照官方约定为你创建主应用和微应用或将现有 Vite 应用改造为微应用。在一个空的工作目录中执行mkdir qiankun-demo cd qiankun-demo npx skills add umijs/qiankun该命令会从 qiankun 仓库拉取名为qiankun的 skill并安装到当前 agent 的技能目录例如.claude/skills/。skill 与文档站同源维护agent 生成的项目结构与教程手动搭建的结果完全一致skill 只是把这份约定交给 agent 执行。安装完成后向 agent 描述目标即可例如用 qiankun 创建一个 React TypeScript 主应用 main-app端口 7099用 loadMicroApp 加载微应用和一个 React TypeScript 微应用 sub-app端口 7101agent 会按 SKILL.md 中的任务路由读取对应参考文件并完成以下工作使用 create-vite 创建项目React 或 VueTypeScript 或 JavaScript微应用安装qiankunjs/bundler-plugin、注册 Vite 插件并固定端口、改写入口模块以导出bootstrap/mount/update/unmount生命周期并保留独立运行分支详见 create-micro-app.md主应用安装qiankun及可选的 React/VueMicroApp组件绑定接入加载代码详见 create-main-app.md启动两个开发服务器验证微应用既能独立运行、也能被主应用加载和卸载。如果你不使用 agent可以按照教程手动搭建完全相同的结构——本页其余内容同样适用。[!NOTE]关于 skill 的版本约定从 SKILL.md 可以看到当前仓库的核心包qiankunpackage.json 中版本为3.0.0-rc.22以及qiankunjs/react、qiankunjs/vue、qiankunjs/bundler-plugin均使用rc作为 dist-tag。skill 会始终拉取与最新文档同步的版本你无需关心 skill 自身的版本号。第二步启动两个开发服务器项目创建完成后打开两个终端在qiankun-demo目录下分别启动两个应用::: code-groupcd sub-app npm install npm run dev # http://localhost:7101cd main-app npm install npm run dev # http://localhost:7099:::然后访问http://localhost:7099查看主应用中挂载的微应用直接访问http://localhost:7101确认微应用能够脱离主应用独立运行。这两个检查全部通过说明主应用与微应用已经按 qiankun 的接入约定连通两个项目在运行时仅通过微应用的 HTML 入口地址产生关联它们各自管理依赖、开发服务器和构建流程无需放进同一个 monorepo。主应用如何管理微应用loadMicroApp 详解生成的主应用运行在7099端口。React 创建容器元素后App.tsx通过以下代码加载微应用import { loadMicroApp } from qiankun; import { useEffect, useRef } from react; export default function App() { const containerRef useRefHTMLDivElement(null); useEffect(() { const container containerRef.current; if (!container) return; const microApp loadMicroApp({ name: sub-app, entry: //localhost:7101, container, }); return () { void microApp.unmount().catch((error: unknown) { console.error(sub-app 卸载失败, error); }); }; }, []); return div ref{containerRef} /; }三个必填字段传给loadMicroApp的配置对象包含三个必填字段字段作用name当前微应用实例的名称。不同容器中的多个实例可以使用同一名称。entry微应用的 HTML 入口。本例指向运行在7101端口的开发服务器。container用于挂载微应用的HTMLElement。从 load-micro-app.md 的函数签名可以看到loadMicroApp接受三个参数app: LoadableAppT、可选的configuration?: AppConfiguration和可选的lifeCycles?: LifeCyclesTfunction loadMicroAppT extends ObjectType( app: LoadableAppT, configuration?: AppConfiguration, lifeCycles?: LifeCyclesT, ): MicroApp;关于这三个字段有两个 v3 的重要变化值得注意entry仅支持字符串。v3 不再支持 2.x 的对象形式{ scripts, styles }container必须是真实的HTMLElement元素不能使用 CSS 选择器字符串。调用前应通过document.getElementById(...)或框架提供的 ref 获取实际元素——传入选择器字符串会导致类型错误运行时也无法正常挂载。MicroApp 句柄保留它并在清理时调用 unmount()loadMicroApp返回一个MicroApp实例句柄其底层类型为 single-spa 的 Parcel。关键行为如下调用后立即开始加载和挂载无需预先调用start()从源码 loadMicroApp.ts 可以看到当started为 false 时qiankun 会在内部自动调用start()以保证主应用调用pushState/replaceState时 popstate 事件能被正确分发在实例存续期间应保留该句柄并在清理时调用unmount()以便 qiankun 执行微应用的unmount生命周期并完成卸载调用方负责卸载不再展示应用时应调用unmount()qiankun 会停用沙箱、清空容器并释放能够追踪的资源与副作用。示例代码中useEffect的清理函数不能返回 Promise因此只是发起卸载并捕获可能的失败如果主应用的清理流程支持异步等待则应在移除容器前await microApp.unmount()。句柄提供的状态与 PromiseMicroApp句柄同时暴露了生命周期状态查询和阶段 Promise详见 load-micro-app.md 的返回值小节成员说明mount()挂载该 Parcel。loadMicroApp会在加载时自动挂载通常无需直接调用。unmount()卸载应用、停用沙箱并清理可追踪的副作用和容器 DOM。不再使用应用时必须调用。update?(props)仅当微应用导出update生命周期时存在用于向运行中的应用传递新的 props。getStatus()返回当前生命周期状态NOT_LOADED、LOADING_SOURCE_CODE、MOUNTED、UNMOUNTING等 12 种取值。loadPromise/bootstrapPromise/mountPromise/unmountPromise分别表示源码加载、bootstrap、挂载、卸载各阶段完成的 Promise。[!WARNING] 加载或挂载失败时这些 Promise 会被拒绝。应通过.catch或try...catch处理错误避免产生未处理的 Promise 拒绝。// 等待应用完成挂载 await microApp.mountPromise; console.log(microApp.getStatus()); // MOUNTED // 不再需要时卸载应用 await microApp.unmount();源码视角同一容器与实例复用的处理深入 loadMicroApp 的源码实现可以看到几个支撑上述行为的底层机制容器 XPath 记忆化源码在调用开始时即计算container的 XPathgetContainerXPath(container)并以name containerXPath作为微应用实例的 ID源码注释明确说明如果将微应用渲染到一个之前渲染过的 DOM 上微应用不会重新加载和求值其生命周期。因此不应依赖模块顶层代码在重新挂载时再次执行每次挂载所需的状态应在mount()中初始化同一容器串行化containerMicroAppsMap记录了挂载在同一个容器上的实例列表后一个实例的mount会等待前一个实例的unmountPromise完成后再执行避免并发问题。所以一个容器在同一时刻只承载一个应用如果连续向同一容器加载应用后一个实例会等待前一个实例卸载卸载后的 GC实例在unmountPromise完成后会从容器映射中清理自身并置空引用使长期存活的重新挂载闭包可以释放 Parcel 对象。微应用的接入要求生成的微应用仍是标准的 Vite 应用仅增加以下两部分 qiankun 接入代码qiankunjs/bundler-plugin为 qiankun 配置 HTML 入口和开发服务器。在vite.config.ts中注册该插件并固定端口import { defineConfig } from vite; import react from vitejs/plugin-react; import { qiankun } from qiankunjs/bundler-plugin/vite; export default defineConfig({ plugins: [react(), qiankun()], server: { port: 7101, strictPort: true, }, });该插件不接收参数为 Vite 提供两项能力详见接入 Vite 应用为开发服务器和预览服务器配置 CORS 响应头使主应用能够获取 HTML 入口和模块依赖在生产构建中为唯一的入口模块脚本添加 qiankun 所需的entry属性。注意Vite 插件必须从qiankunjs/bundler-plugin/vite导入包根路径导出的是 Webpack 插件。qiankun 3 以原生 ESM 方式加载 Vite 应用无需使用 UMD 包装、SystemJS 转换或全局生命周期对象。入口模块导出生命周期入口模块导出bootstrap、mount和unmount可选update。mount在主应用提供的容器内渲染unmount销毁框架根节点。React 版入口的简化形态如下import React from react; import ReactDOM from react-dom/client; import App from ./App; declare global { interface Window { __POWERED_BY_QIANKUN__?: boolean; } } type MountProps { container: HTMLElement }; let root: ReactDOM.Root | undefined; function render(scope: ParentNode) { const node scope.querySelector(#root); if (!node) throw new Error(#root not found); root ReactDOM.createRoot(node); root.render(App /); } export async function bootstrap() {} export async function mount({ container }: MountProps) { render(container); } export async function unmount() { root?.unmount(); root undefined; } if (!window.__POWERED_BY_QIANKUN__) { render(document); }实现生命周期时应遵循以下原则原生 ESM 导出即为生命周期约定不应再将生命周期对象赋值给windowprops.container属于当前微应用实例应在该容器内查询#root或#app不应使用页面级全局选择器——否则会破坏多实例能力并使微应用依赖主应用的文档结构__POWERED_BY_QIANKUN__用于避免入口模块在 qiankun 调用mount之前自行渲染应用通过自身开发服务器独立运行时仍会立即渲染每次调用mount都必须创建完整的应用实例每次调用unmount都必须彻底销毁该实例。重新挂载时模块顶层代码不会再次执行。直接访问7101端口时微应用会走独立运行分支自行渲染。因此该应用既可独立开发也可由主应用加载。完整的生命周期约定见微应用生命周期与 props。何时选择路由驱动registerMicroApps 与 startloadMicroApp是应用代码决定实例何时存在时的首选 API实例的创建和销毁由业务代码页面区域、标签页、弹窗以及由主应用状态控制的微应用决定。如果你的微应用激活状态完全取决于当前 URL则应改用registerMicroApps搭配start由 qiankun 根据路由自动挂载和卸载import { registerMicroApps, start } from qiankun; registerMicroApps([ { name: sub-app, entry: //localhost:7101, container: #micro-app-container, activeRule: /sub-app, }, ]); start();两种方式采用相同的微应用契约bootstrap/mount/unmount区别仅在于挂载与卸载的时机由谁决定。本页快速上手流程无需使用这两个 API——loadMicroApp会自动调用start()而路由驱动场景才需要显式调用。更多细节见 registerMicroApps 与 start。常见问题与排查在验证挂载、卸载和独立运行时如果遇到问题可对照以下检查清单整理自运行并验证教程现象检查项容器为空同时入口请求失败确认sub-app运行在7101端口并且entry指向//localhost:7101。浏览器报告 CORS 错误确认微应用的 Vite 配置包含来自qiankunjs/bundler-plugin/vite的qiankun()。qiankun 找不到生命周期函数确认入口模块导出了bootstrap、mount和unmount并且 Vite 配置包含 qiankun 插件。应用首次出现但无法正常重新挂载确认微应用在unmount中销毁了 React 根节点并且主应用调用了句柄的unmount()。Vite 在其他端口启动添加strictPort: true释放7099和7101端口后重新启动。其中 CORS 检查尤其关键插件仅为 Vite 开发服务器和预览服务器启用 CORS。在生产环境中服务器或 CDN 必须允许主应用所在的源获取 HTML 入口、JavaScript 模块、动态导入的代码块以及 CSS、图片等资源如果应用请求需要携带 Cookie则不能将Access-Control-Allow-Origin配置为通配符。另外ESM 微应用请使用基于 Chromium 的浏览器Chrome、Edge 等或 Safari 验证Firefox 目前还不支持 ESM 沙箱所需的动态注入 import map。总结与下一步至此你已经通过 Agent skill 创建并运行了一个完整的 qiankun 最小工程主应用通过loadMicroApp加载微应用并管理其生命周期微应用既是标准的 Vite 应用又能被主应用加载。回顾本文的关键要点主应用提供三要素name、entryHTML 入口字符串、container真实 DOM 元素微应用导出四生命周期bootstrap/mount/update/unmount并在非 qiankun 环境下走独立运行分支实例生命周期由主应用负责保留MicroApp句柄在清理时调用unmount()ESM 微应用无需专用构建模式qiankun 3 原生加载script typemodule常规的vite dev/vite build产物开箱即用。接下来可以继续深入按照教程一步步手动搭建相同结构理解每一步的接入约定在微应用生命周期与 props中了解应用契约的完整细节改造一个现有的 Vite 或 Webpack 应用在loadMicroAppAPI中查看全部选项和方法如sandbox配置、lifeCycles钩子、自定义fetch等参考仓库中的 examples/main/src/apps.ts了解多微应用、多技术栈React / Vue / Webpack / 纯 HTML / Streaming的主应用是如何组织入口与路由的。赞分享前端微前端【免费下载链接】qiankun Blazing fast, simple and complete solution for micro frontends.项目地址https://gitcode.com/gh_mirrors/qi/qiankun点击查看免费下载相关推荐MoneyPrinterV2架构优化如何通过模块化扩展突破自动化内容生成瓶颈MoneyPrinterV2架构优化如何通过模块化扩展突破自动化内容生成瓶颈 在数字内容创作领域自动化工具正从简单的脚本工具演变为完整的生态系统。Money前端微前端qiankun 主应用构建指南用 loadMicroApp 挂载与释放子应用实例qiankun 主应用构建指南用 loadMicroApp 挂载与释放子应用实例 本指南是 qiankun 官方教程「构建主应用与子应用」的第二步手把手教你前端微前端3分钟上手COLA用Archetype快速搭建分层应用3分钟上手COLA用Archetype快速搭建分层应用 你还在为复杂项目的架构设计头疼还在手动创建包结构浪费时间本文将带你3分钟内使用COLA的Arche后端上一篇Obsidian Kanban完全指南10个技巧让你成为看板大师下一篇Mattermost-Docker完全指南从部署到迁移的终极教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考