qiankun 学习笔记

一、qiankun 简介

qiankun 是蚂蚁金服开源的微前端解决方案，基于 single-spa 进行了封装和扩展。

核心特性：

📦 基于 single-spa 封装，提供了更简洁的 API
🛡️ 完善的沙箱隔离机制
🧩 技术栈无关，支持各种前端框架
🔨 HTML Entry 方式加载子应用
💪 样式隔离能力

二、安装依赖

# 主应用安装qiankun
npm i qiankun -S
# 或
yarn add qiankun

三、主应用配置步骤

注册子应用

// 主应用 src/micro/index.js
import { registerMicroApps, start } from "qiankun";

// 注册子应用
registerMicroApps([
  {
    name: "app1", // 子应用名称，唯一
    entry: "//localhost:8081", // 子应用入口，可以是html或js
    container: "#container", // 子应用挂载节点
    activeRule: "/app1", // 激活规则，当路由匹配时激活
    props: { data: "customProps" }, // 传递给子应用的数据
  },
  {
    name: "app2",
    entry: "//localhost:8082",
    container: "#container",
    activeRule: "/app2",
  },
]);

// 启动微前端
start();

创建容器节点

<!-- 主应用中创建容器 -->
<div id="container"></div>

配置启动参数（可选）

start({
  prefetch: "all", // 预加载所有子应用
  sandbox: {
    strictStyleIsolation: false, // 是否使用shadow dom隔离
    experimentalStyleIsolation: true, // 添加选择器前缀隔离样式
  },
});

四、子应用适配步骤

以 Vue 项目为例：

修改 webpack 配置

// vue.config.js
const { name } = require("./package");

module.exports = {
  // 确保子应用的publicPath正确
  publicPath: process.env.NODE_ENV === "production" ? "/app1/" : "/",

  configureWebpack: {
    output: {
      // 打包为umd库格式
      library: `${name}-[name]`,
      libraryTarget: "umd",
      chunkLoadingGlobal: `webpackJsonp_${name}`,
    },
  },

  // 开发环境允许跨域
  devServer: {
    headers: {
      "Access-Control-Allow-Origin": "*",
    },
  },
};

入口文件改造

// src/main.js
import Vue from "vue";
import App from "./App.vue";
import router from "./router";
import store from "./store";
// 用于处理publicPath问题
import "./public-path";

// 保存Vue实例
let instance = null;

// 渲染函数
function render(props = {}) {
  const { container } = props;

  // 创建Vue实例
  instance = new Vue({
    router,
    store,
    render: (h) => h(App),
  });

  // 挂载到指定节点
  instance.$mount(container ? container.querySelector("#app") : "#app");
}

// 独立运行时直接渲染
if (!window.__POWERED_BY_QIANKUN__) {
  render();
}

// 导出微前端生命周期钩子
export async function bootstrap() {
  console.log("app bootstraped");
}

export async function mount(props) {
  console.log("app mounted", props);
  render(props);
}

export async function unmount() {
  console.log("app unmounted");
  instance.$destroy();
  instance = null;
}

创建 public-path.js

// src/public-path.js
if (window.__POWERED_BY_QIANKUN__) {
  __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;
}

调整路由配置

// router/index.js
const router = new VueRouter({
  mode: 'history',
  // 重要：根据运行环境设置base路径
  base: window.__POWERED_BY_QIANKUN__ ? '/app1' : '/',
  routes: [...]
});

五、应用间通信

qiankun 提供了三种通信方式：

基于 props 传递

// 主应用注册时传递
registerMicroApps([
  {
    name: "app1",
    // ...
    props: { token: "xxx", utils: myUtils },
  },
]);

// 子应用在mount钩子中接收
export async function mount(props) {
  console.log(props.token);
  render(props);
}

基于全局状态管理

// 主应用初始化状态
import { initGlobalState } from "qiankun";
const actions = initGlobalState({ user: "admin" });

// 监听状态变化
actions.onGlobalStateChange((state, prev) => {
  console.log("主应用状态变化", state, prev);
});

// 更新状态
actions.setGlobalState({ user: "user123" });

// 子应用获取状态
export function mount(props) {
  props.onGlobalStateChange((state) => {
    console.log("子应用接收到状态", state);
  });

  // 子应用更新状态
  props.setGlobalState({ count: 1 });
}

自定义事件

// 发送事件
window.dispatchEvent(
  new CustomEvent("app-event", {
    detail: { type: "message", data: {} },
  })
);

// 监听事件
window.addEventListener("app-event", (e) => {
  console.log(e.detail);
});

六、常见问题与解决方案

1. 样式隔离

qiankun 提供两种样式隔离方案：

// 1. Shadow DOM隔离(完全隔离，但有一些限制)
start({
  sandbox: { strictStyleIsolation: true },
});

// 2. 前缀选择器隔离(推荐)
start({
  sandbox: { experimentalStyleIsolation: true },
});

2. 资源加载错误

// 检查子应用publicPath设置
if (window.__POWERED_BY_QIANKUN__) {
  __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;
}

3. 路由冲突

// 子应用路由设置正确的base
const base = window.__POWERED_BY_QIANKUN__ ? "/app1" : "/";
const router = new VueRouter({
  mode: "history",
  base,
  routes,
});

七、最佳实践总结

应用拆分原则：
- 按业务域拆分，而非技术维度
- 尽量减少应用间通信和依赖
- 公共依赖提取到主应用
性能优化：
- 启用 prefetch 预加载
- 配置 webpack splitChunks
- 提取公共库到 CDN
开发调试：
- 支持独立开发和联调模式
- 使用环境变量区分
```
if (!window.__POWERED_BY_QIANKUN__) {
  render();
}
```
生产部署：
- 子应用可独立部署
- 使用 Nginx 配置路由转发

八、个人心得

qiankun 极大降低了微前端的实施难度，封装了很多复杂细节
样式隔离仍是最容易出问题的地方，建议团队约定 BEM 命名规范
合理的应用拆分比技术实现更重要
应用间通信尽量减少，数据共享优先考虑公共服务

这份学习笔记记录了我在项目中使用 qiankun 的主要心得。微前端不是银弹，适合中大型团队和应用，小项目反而会增加复杂度。希望这些笔记对你有所帮助！