vite-plugin-qiankun 完整指南：三步在 Vite 中搞定 qiankun 微前端子应用

vite-plugin-qiankun 完整指南：三步在 Vite 中搞定 qiankun 微前端子应用

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

想在 Vite 项目里快速接入 qiankun 微前端？vite-plugin-qiankun 正是为此而生——它保留 Vite 的 ESM 特性，让子应用接入只需一步配置。本文带你走通全流程。

为什么单个 Vite 项目直接跑不了乾坤微前端？

先抛个灵魂拷问：你的 Vite 子应用明明能独立跑起来，为什么主应用一加载它就"装死"？

问题出在几个地方：

• 生命周期对不上。qiankun 需要拿到子应用的 bootstrap / mount / unmount 三个函数，而 Vite 入口是标准 ES module，默认不会把生命周期挂到全局，主应用拿不到；
• 资源没拆开。子应用的代码和公共库（Vue、React 等）混在一个大包里，多个子应用同页加载时重复下载，白白浪费流量；
• 开发模式不友好。Vite dev 下脚本是固定路径的 module 标签，没法直接塞进乾坤的加载流程里。

一句话：Vite 微前端场景需要一层"翻译"，把标准 Vite 产物翻译成 qiankun 认识的形态。vite-plugin-qiankun 干的就是这件事。

qiankun 接入的三步：安装、配置、导出生命周期

1️⃣ 安装插件

一行命令搞定（建议放在开发依赖里）：

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

2️⃣ vite.config 怎么配

在vite.config.ts里注册插件，注意base必须与子应用名保持一致：

import { defineConfig } from 'vite' import qiankun from 'vite-plugin-qiankun' export default defineConfig({ base: '/my-sub-app/', plugins: [ qiankun('my-sub-app') ] })

qiankun()的入参就是子应用名，必须和主应用注册时用的名字完全一致；base决定了子应用资源的访问前缀，两者错一位，资源就会 404。

3️⃣ 子应用入口导出生命周期函数

在子应用入口文件里导出三个 async 函数，插件会自动把它们挂到主应用可感知的位置：

const app = createApp(App) export async function bootstrap() { console.log('子应用已就绪') } export async function mount(props) { app.mount(props.container ? props.container.querySelector('#app') : document.getElementById('app')) } export async function unmount() { app.unmount() }

这样，qiankun 主子应用之间就打通了——主应用负责"喊人"，子应用负责"响应"。

核心机制拆解：插件到底替你做了什么

📦 自动化分包：每个子应用住进自己的储物间

插件会把子应用代码自动分割成独立 chunk，按需加载。就像每户人家有独立储物间，你只搬自己那屋的东西，不会把整栋楼打包。

🚀 公共依赖只加载一次：整层楼共用一部电梯

像 Vue、React 这类公共库会被单独打进公共 chunk，首次进入页面时预加载一次，之后的子应用直接复用。相当于全楼共用一部电梯，谁都不用再单独装。

🧱 沙箱隔离：每个隔间里怎么折腾都不影响邻居

插件为每个子应用生成独立沙箱。子应用里随便改全局变量、乱挂样式，都锁在自己的隔间里，同页渲染多个子应用时互不串扰，稳定性由此而来。

机制	解决的问题	生活化类比
自动化分包	子应用代码独立成 chunk，按需加载	每户独立储物间
公共依赖 chunk	公共库只下载一次，省流量省时间	整层楼共用一部电梯
沙箱隔离	多子应用同页运行互不干扰	每个隔间独立，互不影响

微前端落地：这些坑我们替你踩过了

• ⚠️base 与子应用名必须严格对应，这是 404 报错的第一大来源；
• ⚠️ 生命周期函数必须从入口模块导出且为 async，写在组件内部插件是找不到的；
• 💡 本地联调时给主应用配好代理，子应用 dev 端口固定下来，避免频繁改动主应用配置；
• 💡 子应用内部尽量别直接改写全局对象——沙箱能兜住大部分情况，但别把隔离当保险去依赖；
• 💡 保持主、子应用 Vite 版本一致（插件要求 vite >= 2），减少构建行为差异带来的灵异问题。

结语：把生态凑齐，微前端落地才算完整

vite-plugin-qiankun 的价值，是让 Vite 子应用以最小成本变成合格的 qiankun 公民：三步接入、分包与沙箱自动搞定。搭配建议如下：

生态角色	一句话点评
Qiankun	基于 Single-SPA 的微前端框架，负责主子应用的调度与加载
Vite	提供秒级热更的开发体验，是本插件的运行土壤
Vue3	组合式 API 让子应用代码更轻，适合快速拆分模块
React	与 Vite 配合成熟，React 子应用同样三步接入

按这套组合走下来，微前端落地不再是"大工程"，而是可以按子应用粒度持续推进的日常迭代。

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