前端微前端【免费下载链接】qiankun Blazing fast, simple and complete solution for micro frontends.项目地址https://gitcode.com/gh_mirrors/qi/qiankun点击查看免费下载导读本指南对应 qiankun 教程的收官步骤「Step 3 — Connect, run, and verify」。在前两步分别构建好sub-app微应用与main-app主应用之后本文带你启动两台开发服务器、验证加载—挂载—卸载的完整生命周期契约、确认生产构建可用并系统排查首跑常见的五大问题。读完本文你将掌握一套可复现的「启动 → 验证 → 构建 → 排错」闭环并理解loadMicroApp句柄、Vite 构建插件与 ESM 沙箱在这些行为背后的源码级原理。前置准备两个应用与两份契约在开始运行之前先明确整套教程的布局详见 教程总览main-app运行在http://localhost:7099拥有一个HTMLElement容器决定微应用何时存在sub-app运行在http://localhost:7101导出 qiankun 生命周期函数同时也能独立运行两个项目拥有各自独立的依赖、开发服务器与构建产物唯一的运行时连接是sub-app的 HTML entry URL。主应用侧需要提供三项输入应用name、指向微应用 HTML 的entry字符串、以及一个真实存在的HTMLElement容器。微应用侧需要导出bootstrap、mount、unmount。qiankun 负责连接两端并返回一个句柄主应用必须在实例不再需要时调用该句柄的unmount()。这三项输入正是loadMicroApp的调用契约type LoadableAppT extends Recordstring, unknown { name: string; entry: string; container: HTMLElement; props?: T; };注意 v3 中container必须是真实元素而非 CSS 选择器字符串传入前请先自行解析如document.getElementById(...)。启动两台开发服务器从qiankun-tutorial目录打开两个终端先启动微应用再启动主应用::: code-groupcd sub-app npm run dev # http://localhost:7101cd main-app npm run dev # http://localhost:7099:::务必先启动sub-app再打开 http://localhost:7099。如果顺序颠倒主应用首次拉取 entry 时微应用服务器尚未就绪会直接命中教程排错表中的「entry 请求失败」症状。为什么微应用要在固定端口开发sub-app的 Vite 配置中应当使用固定端口并启用strictPort参考 Prepare a Vite micro-app 中的配置示例export default defineConfig({ plugins: [react(), qiankun()], server: { port: 7101, strictPort: true, }, });原因很直接主应用通过entry: //localhost:7101这一硬编码 URL 加载微应用。若 Vite 因端口占用而自动换端口entry 就会指向一个空地址导致容器空白。排错表中Vite starts on another port一行的解法正是strictPort: true加释放7099/7101两个端口。开发服务器为何能跨域被主应用拉取main-app在:7099sub-app在:7101两者跨源。qiankun v3 通过 ESM 沙箱原生加载 Vite 应用因此开发服务器必须返回宽松的 CORS 头。这一点由 bundler 插件的 Vite 实现自动完成见 packages/bundler-plugin/src/vite/index.tsexport function qiankun(): Plugin { const corsHeaders { Access-Control-Allow-Origin: * }; return { name: qiankun, config(): UserConfig { return { server: { cors: true, headers: corsHeaders }, preview: { cors: true, headers: corsHeaders }, }; }, // ... }; }这正是排错表中CORS error一行的根因所在如果浏览器报 CORS 错误首先要确认微应用的 Vite 配置里确实加入了qiankun()从qiankunjs/bundler-plugin/vite导入注意是/vite子路径包的裸导入是 Webpack 插件。验证生命周期行为打开http://localhost:7099后依次执行以下四项检查初始渲染页面显示 main-app 标题、按钮以及由sub-app渲染的 UI。这是loadMicroApp加载 entry、解析mount导出并挂载到容器中的结果。卸载点击Unmount micro-app。React 移除MicroAppSlot其清理逻辑调用保存的句柄的unmount()方法微应用 UI 消失。重新挂载点击Mount micro-app。创建新的 slot 与新的MicroApp句柄应用重新出现。独立运行直接打开http://localhost:7101同一个sub-app在没有主应用的情况下正常渲染。这四项检查足以确认集成契约成立主应用无需知道微应用内部如何渲染它只拥有容器和返回的句柄。从源码看「卸载→重挂」到底发生了什么loadMicroApp是本次验证的核心 API其实现位于 packages/qiankun/src/apis/loadMicroApp.ts。几个关键行为值得对照验证结果理解加载即挂载loadMicroApp内部通过mountRootParcel立即开始加载并挂载不需要先调用start()start()只会在未启动时被内部自动触发源码 L95-L101。所以第 1 步页面打开就能看到微应用 UI。返回句柄返回的MicroApp是 single-spa Parcel包含mount()、unmount()、update?()、getStatus()以及loadPromise/bootstrapPromise/mountPromise/unmountPromise。第 2 步中 React 组件卸载时调用的正是句柄上的unmount()。同容器串行源码维护containerMicroAppsMap以「应用名 容器 XPath」为键。当同一个容器先后挂载多个实例时后一个实例的mount会先等待前一个实例的unmountPromise完成L32-L46。这保证了第 3 步「重新挂载」不会与新旧实例产生并发冲突。生命周期复用缓存以「name container XPath」为实例 ID同一容器再次渲染同名应用时不会重新加载与求值其生命周期代码L67-L93。因此微应用不得依赖模块顶层代码在重挂时重新执行bootstrap只在首次加载时运行mount可以多次运行unmount必须反转mount产生的所有可见副作用——这正是教程中app appears once but does not remount cleanly一行的理论背景。为了验证卸载后确实释放了容器可以像 e2e 测试夹具那样读取句柄状态见 e2e/fixtures/main/src/main.ts 中load的写法const app loadMicroApp({ name, entry, container, props }, configuration); instances.set(key, app); await app.mountPromise; return app.getStatus(); // 挂载完成后为 MOUNTED生命周期导出的正确形态微应用侧的生命周期契约在 Micro-app lifecycle and props 中有完整定义每个微应用必须导出bootstrap、mount、unmountupdate可选。对 ESMVite应用而言直接在入口模块用命名导出即可对经典构建UMD/Webpack则通过打包产物暴露同一生命周期对象。e2e 夹具 e2e/fixtures/sub-classic/entry.js 展示了经典形式把bootstrap/mount/unmount挂到global上并在mount中基于props.container渲染。这也是排错表中qiankun cannot find lifecycle functions一行的检查要点确认入口模块确实导出了这三个函数、且 Vite 配置包含了 qiankun 插件。构建两个应用在把整套设置迁移进更大项目之前先确认两个生产构建都能成功::: code-groupcd sub-app npm run buildcd main-app npm run build:::微应用的 bundler 插件会在这次构建中准备好它的生产 HTML entry。构建时发生了什么entry属性标记Vite 插件在构建期还有一个关键职责把入口模块脚本标记上entry属性让 loader 能确定性地识别入口而不是回退到最后一个 module script。见 packages/bundler-plugin/src/vite/index.tstransformIndexHtml: { order: post, handler(html, ctx) { const entryChunk ctx.chunk; if (!entryChunk) return html; // 匹配与 entry chunk 同名的 module script 并打上 entry 属性 const matched moduleScripts.filter((_, el) { /* ... */ }); const target matched.length 0 ? matched.first() : moduleScripts.last(); target.attr(entry, ); return $.html(); }, },构建完成后可以检查dist/index.html应当恰好有一个生成的 module script 携带entry属性且不应多于一个。开发态则无需该标记因为 ESM 引擎通过生命周期导出解析入口Vite 在 dev transform 时本来就会丢弃未知属性。常见首跑问题排查下表覆盖首次运行最可能遇到的五个症状及对应检查项症状检查项容器一直空白entry 请求失败确认sub-app正在7101端口运行且entry指向//localhost:7101。浏览器报 CORS 错误确认微应用的 Vite 配置包含qiankunjs/bundler-plugin/vite的qiankun()插件。qiankun 找不到生命周期函数确认入口模块导出了bootstrap、mount、unmount且 Vite 配置包含 qiankun 插件。应用只出现一次无法干净地重挂确认微应用unmount中销毁了 React root且主应用调用了句柄的unmount()。Vite 启动了其他端口加上strictPort: true并在重新启动前释放7099与7101端口。前两类症状的底层成因已在「开发服务器为何能跨域被主应用拉取」一节给出源码依据第三类对应生命周期导出契约见 Micro-app lifecycle and props第四类对应上文「从源码看卸载→重挂」中的生命周期复用缓存行为——unmount必须完整销毁mount创建的 React root否则重挂时会出现重复 root、重复监听器或陈旧 UI。浏览器兼容性提醒对于 ESM 微应用请使用基于 Chromium 的浏览器或 Safari。Firefox 目前不支持 ESM 沙箱所需的动态注入 import maps。这是 qiankun v3 原生 ESM 加载路线的已知边界详见 Native ESM support。进阶验证把「挂载失败」也纳入检查教程的四步验证假设一切顺利。在真实项目中还应验证失败路径mountPromise在加载或挂载失败时会 reject建议像 Handle micro-app errors 那样给句柄挂上拒绝处理避免出现未处理的 Promise rejection同时保留句柄的所有权以便兜底卸载const mountFinished microApp.mountPromise .then(() true) .catch(() { container.replaceChildren( Object.assign(document.createElement(p), { role: alert, textContent: This section could not be loaded., }), ); return false; }); export async function disposeMicroApp() { const mounted await mountFinished; if (mounted) { await microApp.unmount(); } }这一模式与教程第 2、3 步的「卸载→重挂」检查互补正常路径验证契约成立失败路径验证主应用具备恢复能力。下一步通过loadMicroAppprops 向实例传数据了解 Lifecycle and props 中的保证与责任需要时启用 style isolation在主应用中处理 loading 与运行时错误使用 React 或 Vue 绑定获得声明式组件 API——它们底层都是同一个loadMicroApp实例模型。赞分享前端微前端【免费下载链接】qiankun Blazing fast, simple and complete solution for micro frontends.项目地址https://gitcode.com/gh_mirrors/qi/qiankun点击查看免费下载相关推荐qiankun 教程第 3 步运行并验证主应用与微应用的挂载、卸载与独立运行qiankun 教程第 3 步运行并验证主应用与微应用的挂载、卸载与独立运行 本文是 qiankun 官方手动搭建教程的收尾步骤。完成前两步后 main a前端微前端qiankun微应用接入指南3步实现主应用与子应用通信qiankun微应用接入指南3步实现主应用与子应用通信 在现代前端架构中微前端Micro Frontends架构已成为解决大型应用复杂度的有效方案。qi微前端前端框架qiankun 主应用搭建实战使用 loadMicroApp 手动编排微应用实例React Vite 教程第 2 步qiankun 主应用搭建实战使用 loadMicroApp 手动编排微应用实例React Vite 教程第 2 步 主应用是整个微前端架构的页面外前端微前端上一篇Flyway数据库迁移工具add命令详解下一篇OpenMMLab MMSegmentation 配置文件详解与使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
