AIGC标识 qiankun 实战:从零搭建 Vue 3 主应用和子应用,打通双向通信

🧑‍💻 写在开头
点赞 + 收藏 === 学会🤣🤣🤣

这篇文章用两个独立的 Vue 3 Demo 演示 qiankun 的完整流程:安装依赖、注册子应用、配置路由和静态资源、双向传递状态,以及刷新、卸载和跨应用影响的处理。所有示例都可独立于业务项目使用,不包含真实业务代码或环境地址。

最终效果:

  • 点击主应用的「进入子应用」,子应用加载到指定容器;返回「首页」时卸载。
  • 主应用切换主题,子应用随之切换;子应用也能通过共享状态让主应用同步切换。
  • 子应用提交留言,主应用顶部立即显示;切走再回来,留言仍在。整页刷新后,共享内存重置,但主题会从会话缓存恢复。

1. 下载工具和依赖

先从 Node.js 官网 安装 Node.js。建议使用 Node.js 22.12+ 的受支持 LTS 版本,以满足新版 Vite 的运行要求。检查安装结果:

node -v
npm -v

在一个空目录中创建两个项目。示例固定为 Vite 6 脚手架和 qiankun 2 API,避免 latest 升级导致示例配置变化:

npm create vite@6 demo-host -- --template vue
npm create vite@6 demo-child -- --template vue

进入 demo-host,安装主应用依赖:

npm install
npm install qiankun@2 vue-router@4

进入 demo-child,安装子应用依赖:

npm install
npm install -D vite-plugin-qiankun@1.0.15

两个项目是兄弟目录。为避免跨域和代理配置,本例将子应用的构建产物放进主应用的 public 子目录。主应用开发服务和生产产物都能按同一个相对路径提供子应用资源。

workspace/
├── demo-host/
│   ├── public/
│   │   └── micro-apps/demo-child/    # 子应用构建生成
│   └── src/
│       ├── App.vue
│       └── main.js
└── demo-child/
    ├── src/
    │   ├── App.vue
    │   └── main.js
    └── vite.config.js

2. 配置子应用:资源路径与生命周期

修改子应用的 vite.config.js。base 决定构建后 JS、CSS 等资源的访问前缀;outDir 只指向专门存放该子应用产物的目录。emptyOutDir: true 会在构建时清理这个目录,不要把它指向主应用的整个 public。

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import qiankun from 'vite-plugin-qiankun';

export default defineConfig({
  base: '/micro-apps/demo-child/',
  plugins: [vue(), qiankun('demo-child')],
  build: {
    outDir: '../demo-host/public/micro-apps/demo-child',
    emptyOutDir: true,
  },
});

保持 Vite 模板的 index.html 含有 <div id="app"></div> 和指向 /src/main.js 的模块脚本。修改子应用的 src/main.js:

import { createApp } from 'vue';
import {
  qiankunWindow,
  renderWithQiankun,
} from 'vite-plugin-qiankun/dist/helper';
import App from './App.vue';

let app;

function render(props = {}) {
  // 嵌入主应用时,只在 qiankun 提供的容器内查找挂载点。
  const target = props.container
    ? props.container.querySelector('#app')
    : document.querySelector('#app');

  if (!target) throw new Error('找不到子应用挂载点');

  app = createApp(App, {
    onGlobalStateChange: props.onGlobalStateChange,
    offGlobalStateChange: props.offGlobalStateChange,
    setGlobalState: props.setGlobalState,
  });
  app.mount(target);
}

renderWithQiankun({
  async bootstrap() {},
  async mount(props) {
    render(props);
  },
  async unmount() {
    app?.unmount();
    app = undefined;
  },
});

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

bootstrap 用于首次初始化,mount 在进入子应用时创建 Vue 实例,unmount 在离开时销毁实例。不要用全局的 document.querySelector('#app') 挂载嵌入模式,否则主、子应用都用 #app 时可能选中主应用根节点。

接着修改子应用的 src/App.vue:

<script setup>
import { computed, onMounted, onUnmounted, ref } from 'vue';

const props = defineProps({
  onGlobalStateChange: Function,
  offGlobalStateChange: Function,
  setGlobalState: Function,
});

const theme = ref('light');
const draft = ref('');
const connected = computed(() => Boolean(props.setGlobalState));

onMounted(() => {
  props.onGlobalStateChange?.((state) => {
    theme.value = state.theme;
  }, true); // true:订阅时立即收到当前状态,而不是等下一次变化。
});

onUnmounted(() => {
  props.offGlobalStateChange?.();
});

function toggleTheme() {
  const nextTheme = theme.value === 'dark' ? 'light' : 'dark';
  if (connected.value) props.setGlobalState({ theme: nextTheme });
  else theme.value = nextTheme;
}

function sendMessage() {
  const message = draft.value.trim();
  if (!message || !connected.value) return;
  props.setGlobalState({ message });
  draft.value = '';
}
</script>

<template>
  <section class="child-panel" :class="{ dark: theme === 'dark' }">
    <h2>子应用面板</h2>
    <p>子应用主题:{{ theme }}</p>
    <button type="button" @click="toggleTheme">从子应用切换主题</button>
    <form @submit.prevent="sendMessage">
      <label for="demo-message">给主应用留言</label>
      <input id="demo-message" v-model="draft" :disabled="!connected" />
      <button :disabled="!connected || !draft.trim()">发送</button>
    </form>
  </section>
</template>

<style scoped>
.child-panel { padding: 1rem; border: 1px solid #89a0bc; }
.child-panel.dark { color: #f2f5fa; background: #23324b; }
form { display: flex; flex-wrap: wrap; gap: .5rem; margin-top: 1rem; }
</style>

子应用没有直接找主应用 DOM,也没有在 body 上写主题。它只提交共享字段;主应用是否响应、怎么响应,由主应用决定。

3. 配置主应用:注册、路由和共享状态

修改主应用的 src/main.js。主应用负责声明共享字段、注册子应用、控制激活路由;共享状态里的顶级字段预先声明,不依赖子应用临时新增。

import { createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import { initGlobalState, registerMicroApps, start } from 'qiankun';
import App from './App.vue';

const THEME_KEY = 'qiankun-demo:host:theme';

function readTheme() {
  try {
    return sessionStorage.getItem(THEME_KEY) === 'dark' ? 'dark' : 'light';
  } catch {
    return 'light';
  }
}

const initialTheme = readTheme();
const actions = initGlobalState({ theme: initialTheme, message: '' });

const EmptyRoute = { render: () => null };
const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', name: 'home', component: EmptyRoute },
    { path: '/workspace/demo', name: 'demo', component: EmptyRoute },
  ],
});

const app = createApp(App, { actions, initialTheme, themeKey: THEME_KEY });
app.use(router);

router.isReady().then(() => {
  app.mount('#app');

  registerMicroApps([
    {
      name: 'demo-child',
      entry: '/micro-apps/demo-child/index.html',
      container: '#demo-child-container',
      activeRule: (location) => location.pathname === '/workspace/demo',
    },
  ]);

  start({ prefetch: false });
});

qiankun 2 的 onGlobalStateChange 每个应用只保留一个回调。因此下面把主应用的 UI 更新和主题缓存写入放进同一个订阅,而不是在入口与组件各注册一次。

主应用的 src/App.vue:

<script setup>
import { onMounted, onUnmounted, ref } from 'vue';
import { RouterLink, useRoute } from 'vue-router';

const props = defineProps({
  actions: { type: Object, required: true },
  initialTheme: { type: String, required: true },
  themeKey: { type: String, required: true },
});

const route = useRoute();
const theme = ref(props.initialTheme);
const message = ref('');

onMounted(() => {
  props.actions.onGlobalStateChange((state, previousState) => {
    theme.value = state.theme;
    message.value = state.message;
    if (state.theme === previousState.theme) return;
    try {
      sessionStorage.setItem(props.themeKey, state.theme);
    } catch {
      // 浏览器禁用存储时,不影响当前页面交互。
    }
  }, true);
});

onUnmounted(() => {
  props.actions.offGlobalStateChange();
});

function toggleTheme() {
  props.actions.setGlobalState({
    theme: theme.value === 'dark' ? 'light' : 'dark',
  });
}
</script>

<template>
  <main class="host-shell" :class="{ dark: theme === 'dark' }">
    <header>
      <h1>主应用工作台</h1>
      <nav>
        <RouterLink :to="{ name: 'home' }">首页</RouterLink>
        <RouterLink :to="{ name: 'demo' }">进入子应用</RouterLink>
        <button type="button" @click="toggleTheme">从主应用切换主题</button>
      </nav>
      <p>主应用主题:{{ theme }}</p>
      <p>子应用留言:{{ message || '暂无留言' }}</p>
    </header>

    <p v-if="route.name === 'home'">点击导航加载子应用。</p>
    <div id="demo-child-container" v-show="route.name === 'demo'"></div>
  </main>
</template>

<style scoped>
.host-shell { min-height: 100vh; padding: 1.5rem; color: #243247; background: #f7f9fc; }
.host-shell.dark { color: #f2f5fa; background: #17243b; }
nav { display: flex; flex-wrap: wrap; align-items: center; gap: 1rem; }
nav a { color: inherit; }
</style>

这里用 v-show 保留挂载容器,避免路由切换时容器先被 Vue 删除,qiankun 还没来得及卸载。还有三个名字或路径容易混淆:

配置 示例 用来做什么
注册名称 name demo-child 与子应用 Vite 插件里的名称保持一致
加载地址 entry /micro-apps/demo-child/index.html 找子应用的入口 HTML;子应用 base 是其静态资源目录前缀
激活规则 activeRule /workspace/demo 判断何时挂载子应用,与资源目录不是一回事

4. 构建、运行和发布

先在子应用目录执行:

npm run build

再在主应用目录执行:

npm run dev

通过终端提供的入口打开主应用。修改子应用后重新构建,再刷新主页面即可验证;也可以在子应用目录用 npm run build -- --watch 监听构建。这个 Demo 使用子应用构建产物接入,没有配置跨域开发服务或热更新。

发布时依然先构建子应用,再在主应用目录执行 npm run build。Vite 会把 public 下的子应用一同复制到主应用 dist,发布 dist 即可。生产服务器须区分两种路径:

  • /workspace/demo 是主应用的 History 路由,直接访问或刷新时应回退到主应用入口 HTML。
  • /micro-apps/demo-child/index.html 应返回子应用自己的入口 HTML;同目录下的 JS、CSS 按静态文件提供。找不到资源时返回 404,不要用主应用入口 HTML 兜底。

如果迁移到独立域名部署,主应用需要能跨域获取子应用入口 HTML 和资源;在资源服务端针对实际主应用来源配置 CORS,同时重新核对 entry 与资源 base。不需要为了跨域部署关闭浏览器安全策略。

5. 哪些影响是预期的,哪些需要隔离?

场景 推荐处理
主应用改主题,多个子应用同步 主应用定义 theme,子应用订阅读取;各自只给自己的根节点加样式类。
子应用触发宿主操作 少量共享状态可用 setGlobalState;提交订单、打开宿主弹窗等命令更适合由主应用通过 props 提供明确的回调,而不是把共享状态当事件总线。
子应用切走再回来 在卸载时移除共享状态订阅、定时器、全局事件监听,按需取消未完成的请求。不要把卸载等同退出登录。
刷新后顶部导航丢失 如果同源部署,主、子应用看到的是同一套同源存储;子应用不要在挂载或卸载时调用 localStorage.clear(),也不要删除主应用的导航缓存。主应用应独立初始化导航,不依赖子应用先加载。
子应用也需要权限缓存 使用自己的命名空间。登录会话一致且缓存有效时优先读缓存,未命中再请求;退出、换号和权限版本变化时由缓存所有者清理。缓存只用于界面初始化,后端接口仍须逐次鉴权。
样式或组件弹层串到其他应用 让样式限定在应用根节点内,尽量把弹层挂到应用容器。不要假定 qiankun 沙箱能隔离 document.body、共享存储或所有全局样式,也不要把微前端当成不可信代码的安全边界。

initGlobalState 的数据默认在内存里。子应用卸载不等于整个主应用销毁,所以同页切换后仍能读到主题和留言;浏览器整页刷新会重新初始化共享状态。本例只持久化主题,留言刷新后清空。sessionStorage 通常在同一标签页的刷新中保留,不应拿它做跨标签页同步。

6. 验收清单

  1. 打开首页,主应用导航可见,子应用还没挂载。
  2. 进入子应用,主应用和子应用显示相同主题。
  3. 分别从主、子应用切换主题,确认另一侧同步更新;在子应用发送留言,确认主应用顶部立即显示。
  4. 返回首页再进入,主应用导航一直可用,共享留言仍在,子应用输入框重新初始化。
  5. 在子应用路由整页刷新,主应用导航仍可见,子应用重新挂载,主题恢复、留言清空。
  6. 在生产部署上直接打开子应用路由,确认页面和子应用静态资源能正常加载。

整个流程的关键是:路由负责挂载,生命周期负责清理,共享状态负责有意的联动,应用自身负责隔离副作用。

如果对您有所帮助,欢迎您点个关注,我会定时更新技术文档,大家一起讨论学习,一起进步。

图片

posted @ 2026-11-20 18:14  林恒  阅读(9)  评论(0)    收藏  举报