winjs-plugin-qiankun

适配 WinJS 的微前端 qiankun 子应用插件。

功能特性

• 🚀 自动化子应用改造: 自动将 WinJS 应用改造为 qiankun 子应用
• 📦 完整生命周期支持: 提供 bootstrap、mount、unmount、update 生命周期钩子
• 🔧 智能路由配置: 自动处理路由前缀和公共路径，支持 hash 和 browser 模式
• 🎯 运行时检测: 提供运行时检测函数，判断是否在 qiankun 环境中运行
• 📊 缓存机制: 内置应用实例缓存，优化性能
• 🔄 热重载支持: 开发环境支持热重载调试

安装

npm install @winner-fed/plugin-qiankun
# 或
yarn add @winner-fed/plugin-qiankun
# 或
pnpm add @winner-fed/plugin-qiankun

基础使用

1. 在 WinJS 项目中启用插件

在 .winrc.ts 配置文件中添加插件：

import { defineConfig } from 'win';

export default defineConfig({
  plugins: [
    require.resolve('@winner-fed/plugin-qiankun')
  ],
  qiankun: {
    child: {}
  }
});

2. 基础配置

export default defineConfig({
  plugins: [
    require.resolve('@winner-fed/plugin-qiankun')
  ],
  qiankun: {
    child: {
      enable: true,
      devSourceMap: true,
      shouldNotModifyDefaultBase: false,
      shouldNotModifyRuntimePublicPath: false,
      shouldNotAddLibraryChunkName: false
    }
  }
});

配置选项

child 配置

参数	类型	默认值	说明
enable	boolean	true	是否启用子应用功能
devSourceMap	boolean	true	开发环境是否启用 source map
shouldNotModifyDefaultBase	boolean	false	是否不修改默认的 base 路径
shouldNotModifyRuntimePublicPath	boolean	false	是否不修改运行时公共路径
shouldNotAddLibraryChunkName	boolean	false	是否不添加库 chunk 名称

生命周期钩子

export default defineConfig({
  qiankun: {
    child: {
      bootstrap: async (props) => {
        console.log('子应用启动', props);
      },
      mount: async (props) => {
        console.log('子应用挂载', props);
      },
      unmount: async (props) => {
        console.log('子应用卸载', props);
      },
      update: async (props) => {
        console.log('子应用更新', props);
      }
    }
  }
});

运行时 API

isQiankun()

判断当前应用是否运行在 qiankun 环境中：

import { isQiankun } from '@@/plugin-qiankun-child';

if (isQiankun()) {
  console.log('当前运行在 qiankun 环境中');
} else {
  console.log('当前独立运行');
}

运行时配置

在 src/app.js 中进行运行时配置：

export const qiankun = {
  child: {
    bootstrap: async (props) => {
      console.log('子应用启动', props);
    },
    mount: async (props) => {
      console.log('子应用挂载', props);
      // 处理主应用传递的 props
      if (props.token) {
        // 设置认证信息
        localStorage.setItem('token', props.token);
      }
    },
    unmount: async (props) => {
      console.log('子应用卸载', props);
      // 清理资源
      localStorage.removeItem('token');
    },
    update: async (props) => {
      console.log('子应用更新', props);
    }
  }
};

高级功能

路由配置

插件会自动处理路由前缀，支持以下场景：

1. Browser 模式: 自动添加 /${packageName} 前缀
2. Hash 模式: 自动重写路由，添加路由前缀
3. 自定义前缀: 通过主应用传递的 routerPrefix 配置

// 路由配置示例
export const router = {
  scrollBehavior(to, from) {
    // 自定义滚动行为
    return { top: 0 };
  }
};

历史模式支持

export const qiankun = {
  child: {
    mount: async (props) => {
      // 主应用可以传递历史模式配置
      const { history } = props;
      if (history) {
        console.log('使用主应用指定的历史模式:', history);
      }
    }
  }
};

加载状态管理

export const qiankun = {
  child: {
    mount: async (props) => {
      // 手动控制加载状态
      if (props.setLoading) {
        props.setLoading(true);
        
        // 执行初始化逻辑
        await initializeApp();
        
        // 完成后关闭加载状态
        props.setLoading(false);
      }
    }
  }
};

最佳实践

1. 应用隔离

确保子应用的样式和全局变量不会影响主应用：

/* 在子应用中使用 scoped 样式 */
.my-app {
  /* 子应用样式 */
}

2. 状态管理

// 使用 Vuex 或 Pinia 进行状态管理
export const qiankun = {
  child: {
    mount: async (props) => {
      // 从主应用获取初始状态
      if (props.initialState) {
        store.commit('setInitialState', props.initialState);
      }
    },
    unmount: async (props) => {
      // 清理状态
      store.commit('reset');
    }
  }
};

3. 通信机制

export const qiankun = {
  child: {
    mount: async (props) => {
      // 监听主应用消息
      if (props.onGlobalStateChange) {
        props.onGlobalStateChange((state, prev) => {
          console.log('全局状态变化:', state, prev);
        });
      }
      
      // 向主应用发送消息
      if (props.setGlobalState) {
        props.setGlobalState({
          childAppLoaded: true
        });
      }
    }
  }
};

注意事项

1. 包名配置: 确保 package.json 中有正确的 name 字段
2. public-path: 插件会自动处理 publicPath，一般不需要手动配置
3. 样式隔离: 建议使用 CSS Modules 或 styled-components 避免样式冲突
4. 资源加载: 确保静态资源路径正确，避免在子应用中使用绝对路径

故障排除

常见问题

1. 子应用无法正常加载

   • 检查 package.json 中的 name 字段
   • 确认主应用的 entry 配置正确

2. 路由跳转异常

   • 检查路由配置是否正确
   • 确认 base 配置是否符合预期

3. 样式冲突

   • 使用 CSS Modules 或 scoped 样式
   • 避免全局样式污染

调试技巧

// 开启调试模式
export const qiankun = {
  child: {
    mount: async (props) => {
      console.log('子应用 props:', props);
      console.log('是否在 qiankun 环境:', window.__POWERED_BY_QIANKUN__);
    }
  }
};

许可证

MIT.