vite-plugin-qiankun 上手教程：三步让 Vite 项目跑成乾坤子应用

vite-plugin-qiankun 上手教程：三步让 Vite 项目跑成乾坤子应用

【免费下载链接】vite-plugin-qiankun保留vite es特性，快速接入乾坤微前端子应用项目地址: https://gitcode.com/gh_mirrors/vi/vite-plugin-qiankun

vite-plugin-qiankun 是一个 Vite 插件：它让 Vite 构建的应用能以 qiankun 子应用的身份被加载，同时完整保留 Vite 原生的 ESM 输出，不用为了接入微前端而改造构建配置。

什么情况下你会需要它

• 主应用用了 qiankun，要求子应用在window上按应用名暴露生命周期函数；而 Vite 产出的是 ES Module，window['myApp']根本不存在
• 或者你被迫把构建输出改成 UMD 才能被 qiankun 加载，丢掉了 Vite 的开发体验
• 你希望不改动现有vite.config.ts太多，几分钟内完成接入

一句话定位：它是"Vite 子应用"与"乾坤主应用"之间的翻译器。

它替你解决了哪些问题

自动改写 HTML，把生命周期"架"给乾坤

插件在构建或启动服务时会重写 index.html：把<script type="module">换成动态import()，再追加一段脚本，把 bootstrap、mount、unmount、update 注册到window上你的应用名下。可以理解为预留了一个"提货点"——qiankun 先拿到全局生命周期函数，等 ESM 代码加载完成后，再通过 Promise 把真正的执行逻辑交出去。

现有 Vite 配置基本不用动

plugins数组里加一行qiankun('应用名')即可，不涉及 rollup 输出格式、分包等配置的改动，原有的 TypeScript 等插件照常工作。

Vite 开发服务器也能直接当子应用加载

通过useDevMode选项，子应用可以不经过构建、直接从 dev server 被主应用加载，方便调试。代价是这期间要关掉热更新，后文会讲。

三步完成最小可用配置

第 1 步：安装

npm install @sh-winter/vite-plugin-qiankun --save-dev

第 2 步：在 vite.config 中注册

import qiankun from 'vite-plugin-qiankun'; export default { plugins: [qiankun('myMicroAppName')], // 名字须与主应用注册时一致 base: 'http://your-domain.com/' };

第 3 步：在入口声明生命周期

import { renderWithQiankun, qiankunWindow } from 'vite-plugin-qiankun/dist/helper'; renderWithQiankun({ bootstrap() {}, mount(props) { render(props); }, unmount(props) { unmountApp(props); }, }); if (!qiankunWindow.__POWERED_BY_QIANKUN__) { render({}); // 独立运行时照常渲染 }

unmount里记得真正卸载组件（如ReactDOM.unmountComponentAtNode），否则子应用反复切换会越积越卡。

之后在主应用里照常调用registerMicroApps填入 name、entry、container、activeRule，浏览器访问对应路径就能看到子应用渲染出来。仓库example/目录里有完整可运行的 demo：一个 webpack 构建的主应用加 React、Vue2、Vue3 等四个子应用，执行npm run example:install安装依赖，再跑npm run example:start（构建产物模式）或npm run example:start-vite-dev（Vite 开发服务器模式）即可并行启动全部应用。

进阶配置与高频踩坑点

生产环境的 base 与资源路径

base决定所有资源的 URL 前缀。动态注入的import()依赖它定位子应用资源，若与主应用实际加载子应用的域名不一致，脚本会直接加载失败。仓库示例的做法是：构建产物模式下 base 设为完整域名（如http://127.0.0.1:7106/），开发模式设为/，你可参照 example/viteapp/vite.config.ts 的写法。

useDevMode 与热更新的冲突

开发环境直接加载 dev server 作为子应用时，会与热更新插件（以及其它会改 HTML 的插件，如 React refresh）冲突。推荐用变量切换，这也是示例项目的做法：

const useDevMode = true; // true：作为子应用调试，不加刷新插件 // false：保留热更新，但本应用不能被当作子应用加载

注意：你的代码不在 JS 沙箱里

由于 ESM 加载方式与 qiankun 沙箱机制存在冲突，用本插件接入的子应用不运行在 JS 沙箱中。必须写window属性时，走 helper 导出的qiankunWindow：

import { qiankunWindow } from 'vite-plugin-qiankun/dist/helper'; qiankunWindow.myFlag = 'value';

这样写入落在沙箱 window 上，不会污染同页的其它子应用。

📌 常用配置速查：

版本要求：vite >= 2、typescript >= 4（peerDependencies）。

它和谁配合干活

• qiankun：主框架一侧，负责应用注册、activeRule 路由匹配与整体调度；本插件只解决"让 Vite 子应用说 qiankun 的语言"
• Vite：子应用的构建工具，开发服务器与 ESM 产出保持原样
• 主应用：技术栈不限，仓库示例用 webpack 构建的主应用搭配了 Vue3、React18 等多个子应用，混搭没问题

适合哪些团队

• 主应用已用 qiankun，需要接入一个或多个 Vite 子应用
• 子应用基于 Vite 2+，且没有"必须产出 UMD"的历史包袱
• 能接受 JS 沙箱缺失（用qiankunWindow规避），并接受开发期二选一的 HMR 策略

如果你的子应用正是 Vite 构建、主应用正好是 qiankun，今天就可以按上面的三步接进来——整套改动不到 20 行代码。

【免费下载链接】vite-plugin-qiankun保留vite es特性，快速接入乾坤微前端子应用项目地址: https://gitcode.com/gh_mirrors/vi/vite-plugin-qiankun