简介

vite-plugin-qiankun-enhanced: 基于 vite-plugin-qiankun 的修改版

在原版插件基础上，新增了对 vite-plugin-dynamic-base 的完整支持，解决微前端架构中动态部署路径的问题。

核心增强功能：

• ✅ 保留原版所有功能（100% 兼容）
• ✅ 新增 urlTransform 配置选项
• ✅ 支持 vite-plugin-dynamic-base
• ✅ 支持动态部署路径解析

快速开始

1、在 vite.config.ts 中安装插件

// vite.config.ts

import qiankun from 'vite-plugin-qiankun-enhanced';

export default {
  // 这里的 'myMicroAppName' 是子应用名，主应用注册时AppName需保持一致
  plugins: [qiankun('myMicroAppName')],
  // 生产环境需要指定运行域名作为base
  base: 'http://xxx.com/'
}

配置选项：

qiankun('myMicroAppName', {
  useDevMode: boolean,          // 是否开启开发模式（默认 false）
  urlTransform?: (url: string) => string  // 【新增】路径转换函数，用于动态部署
})

示例：使用动态部署路径

qiankun('myMicroAppName', {
  useDevMode: false,
  urlTransform: (ori) => ori.replace("/__dynamic_base__", "")
})

2、在入口文件里面写入乾坤的生命周期配置

// main.ts
import { renderWithQiankun, qiankunWindow } from 'vite-plugin-qiankun-enhanced/dist/helper';

// some code
renderWithQiankun({
  mount(props) {
    console.log('mount');
    render(props);
  },
  bootstrap() {
    console.log('bootstrap');
  },
  unmount(props: any) {
    console.log('unmount');
    const { container } = props;
    const mountRoot = container?.querySelector('#root');
    ReactDOM.unmountComponentAtNode(
      mountRoot || document.querySelector('#root'),
    );
  },
});

if (!qiankunWindow.__POWERED_BY_QIANKUN__) {
  render({});
}

3、dev下作为子应用调试

因为开发环境作为子应用时与热更新插件（可能与其他修改html的插件也会存在冲突）有冲突，所以需要额外的调试配置

// useDevMode 开启时与热更新插件冲突,使用变量切换
const useDevMode = true

const baseConfig: UserConfig = {
  plugins: [
    ...(
      useDevMode ? [] : [
        reactRefresh()
      ]
    ),
    qiankun('viteapp', {
      useDevMode
    })
  ],
}

上面例子中 useDevMode = true 则不使用热更新插件，useDevMode = false 则能使用热更新，但无法作为子应用加载。

4、其它使用注意点 qiankunWindow

因为es模块加载与qiankun的实现方式有些冲突，所以使用本插件实现的qiankun微应用里面没有运行在js沙盒中。所以在不可避免需要设置window上的属性时，尽量显示的操作js沙盒，否则可能会对其它子应用产生副作用。qiankun沙盒使用方式

import { qiankunWindow } from 'vite-plugin-qiankun-enhanced/dist/helper';

qiankunWindow.customxxx = 'ssss'

if (qiankunWindow.__POWERED_BY_QIANKUN__) {
  console.log('我正在作为子应用运行')
}

与 vite-plugin-dynamic-base 集成

本增强版插件专为解决与 vite-plugin-dynamic-base 的兼容性问题而设计。

典型配置：

// vite.config.ts
import qiankun from 'vite-plugin-qiankun-enhanced';
import dynamicBase from 'vite-plugin-dynamic-base';

export default {
  plugins: [
    dynamicBase({
      // 动态基路径配置
      publicPath: "window.__dynamic_base__",
      transformIndexHtml: true,
    }),
    qiankun('mdsdelivery', {
      useDevMode: isDev,  // 开发环境开启，关闭热更新
      // 【关键】urlTransform 函数将自动提取路径标记并生成对应的动态变量
      urlTransform: (ori) => ori.replace("/__dynamic_base__", "")
    })
  ],
}

工作原理：

1. vite-plugin-dynamic-base 生成带有路径标记的脚本：/__dynamic_base__/assets/index.js
2. vite-plugin-qiankun-enhanced 检测到 urlTransform 配置
3. 自动从函数中提取路径前缀：/__dynamic_base__
4. 生成动态导入代码：import(window.__dynamic_base__ + '/assets/index.js')
5. 运行时，window.__dynamic_base__ 变量指向实际部署路径

生成的代码示例：

<script>
  import(window.__dynamic_base__ + '/assets/index.js').finally(() => {
    // 应用加载逻辑
  })
</script>

例子

详细的信息可以参考例子里面的使用方式

git clone xx
npm install
npm run example:install
# 生产环境调试demo
npm run example:start
# vite开发环境demo, demo中热更新已经关闭
npm run example:start-vite-dev

致谢

本项目在以下优秀项目的基础上开发：

• vite-plugin-qiankun - 原版插件，提供了完整的微前端解决方案
• vite-plugin-qiankun-x - 提供了 urlTransform 的设计思路

感谢这些开源项目的作者和贡献者！