微前端架构深度解析：从理论到实践的完整指南

// iframe 内部路由变化不会同步到主应用 URL
iframe.contentWindow.history.pushState({}, '', '/iframe-route');
// 主应用 URL 没有变化，刷新后状态丢失

// 主应用
window.mainAppData = { user: 'alice' };

// iframe 内部无法直接访问
console.log(window.parent.mainAppData); // 可能因为跨域被阻止

// iframe 加载时序
1. 创建新的浏览器上下文
2. 加载 HTML 文档
3. 解析 DOM
4. 加载 CSS 资源
5. 加载 JS 资源
6. 执行 JS 初始化
// 每一步都阻塞，用户体验差

// 主应用 main.js
import { registerApplication, start } from 'single-spa';

// 加载函数：返回 Promise
function loadApp(url, globalVar) {
  return async () => {
    // 动态创建 script 标签加载子应用
    await createScript(url + '/js/chunk-vendors.js');
    await createScript(url + '/js/app.js');
    // 返回子应用暴露的生命周期函数
    return window[globalVar];
  };
}

// 注册子应用
registerApplication({
  name: 'app1',
  app: loadApp('http://localhost:8081', 'app1'),
  activeWhen: location => location.pathname.startsWith('/app1'),
  customProps: {}
});

registerApplication({
  name: 'app2',
  app: loadApp('http://localhost:8082', 'app2'),
  activeWhen: location => location.pathname.startsWith('/app2'),
  customProps: { domElement: document.getElementById('microApp') }
});

// 启动
start();

// React 子应用入口
import React from 'react';
import ReactDOM from 'react-dom';
import rootComponent from './App';

// 独立运行时的渲染
if (!window.singleSpaNavigate) {
  ReactDOM.render(rootComponent(), document.getElementById('root'));
}

// 导出生命周期函数
export async function bootstrap(props) {
  console.log('app bootstrap');
}

export async function mount(props) {
  console.log('app mount');
  ReactDOM.render(rootComponent(), props.domElement || document.getElementById('root'));
}

export async function unmount(props) {
  console.log('app unmount');
  ReactDOM.unmountComponentAtNode(props.domElement || document.getElementById('root'));
}

// webpack.config.js
const package = require('./package.json');

module.exports = {
  output: {
    library: package.name,
    libraryTarget: 'umd',
    // webpack 5 需要
    chunkLoadingGlobal: `webpackJsonp_${package.name}`,
    globalObject: 'window'
  },
  devServer: {
    port: 8081,
    headers: {
      'Access-Control-Allow-Origin': '*'
    }
  }
};

// 生命周期时序
Load → Bootstrap → Mount → Unmount

// 详细说明
bootstrap: 应用初始化，只执行一次
mount: 应用激活，每次进入时执行
unmount: 应用卸载，每次离开时执行
update: 可选，应用更新时执行

// 主应用 main.js
import { registerMicroApps, start, initGlobalState } from 'qiankun';

// 注册子应用
registerMicroApps([
  {
    name: 'react-app',
    entry: '//localhost:7100',
    container: '#subapp-container',
    activeRule: '/react-app',
    props: {
      routerBase: '/react-app'
    }
  },
  {
    name: 'vue-app',
    entry: '//localhost:7200',
    container: '#subapp-container',
    activeRule: '/vue-app'
  }
]);

// 初始化全局状态
const { onGlobalStateChange, setGlobalState } = initGlobalState({
  user: 'qiankun',
  token: ''
});

// 监听状态变化
onGlobalStateChange((value, prev) => {
  console.log('[主应用] state change:', value, prev);
});

// 启动
start({
  prefetch: true,  // 预加载
  sandbox: {
    strictStyleIsolation: true,  // 严格样式隔离
    // experimentalStyleIsolation: true  // 实验性样式隔离
  }
});

// React 子应用入口 src/public-path.js
if (window.__POWERED_BY_QIANKUN__) {
  __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;
}

// React 子应用入口 src/index.js
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

function render(props) {
  const { container } = props;
  ReactDOM.render(
    <App />,
    container ? container.querySelector('#root') : document.querySelector('#root')
  );
}

// 独立运行
if (!window.__POWERED_BY_QIANKUN__) {
  render({});
}

// 生命周期
export async function bootstrap() {
  console.log('[React App] bootstraped');
}

export async function mount(props) {
  console.log('[React App] mount, props:', props);
  render(props);

  // 监听全局状态
  props.onGlobalStateChange((state, prev) => {
    console.log('[React App] state change:', state, prev);
  });
}

export async function unmount(props) {
  const { container } = props;
  ReactDOM.unmountComponentAtNode(
    container ? container.querySelector('#root') : document.querySelector('#root')
  );
}

// React 子应用 .rescriptsrc.js 或 config-overrides.js
const { name } = require('./package.json');

module.exports = {
  webpack: (config) => {
    config.output.library = `${name}-[name]`;
    config.output.libraryTarget = 'umd';
    config.output.jsonpFunction = `webpackJsonp_${name}`;
    config.output.globalObject = 'window';
    return config;
  },
  devServer: (_) => {
    const config = _;
    config.headers = {
      'Access-Control-Allow-Origin': '*',
    };
    config.historyApiFallback = true;
    config.hot = false;
    config.watchContentBase = false;
    config.liveReload = false;
    return config;
  },
};

class SnapshotSandbox {
  constructor() {
    this.windowSnapshot = {};
    this.modifyPropsMap = {};
  }

  // 激活沙箱
  active() {
    // 保存当前 window 快照
    this.windowSnapshot = {};
    for (const prop in window) {
      if (window.hasOwnProperty(prop)) {
        this.windowSnapshot[prop] = window[prop];
      }
    }

    // 恢复上次的修改
    Object.keys(this.modifyPropsMap).forEach(p => {
      window[p] = this.modifyPropsMap[p];
    });
  }

  // 失活沙箱
  inactive() {
    const modifyPropsMap = {};
    // 对比差异，记录修改
    for (const prop in window) {
      if (window[prop] !== this.windowSnapshot[prop]) {
        modifyPropsMap[prop] = window[prop];
        // 恢复环境
        window[prop] = this.windowSnapshot[prop];
      }
    }
    this.modifyPropsMap = modifyPropsMap;
  }
}

class LegacySandbox {
  constructor() {
    this.addedPropsMapInSandbox = {};
    this.modifiedPropsOriginalValueMapInSandbox = {};
    this.currentUpdatedPropsValueMap = {};

    const fakeWindow = Object.create(null);

    this.proxyWindow = new Proxy(fakeWindow, {
      set(target, p, value) {
        if (!window.hasOwnProperty(p)) {
          this.addedPropsMapInSandbox[p] = value;
        } else if (!this.modifiedPropsOriginalValueMapInSandbox.hasOwnProperty(p)) {
          this.modifiedPropsOriginalValueMapInSandbox[p] = window[p];
        }
        this.currentUpdatedPropsValueMap[p] = value;
        window[p] = value;
        return true;
      },
      get(target, p) {
        return window[p];
      }
    });
  }
}

class ProxySandbox {
  constructor() {
    const rawWindow = window;
    const fakeWindow = {};

    this.proxy = new Proxy(fakeWindow, {
      set(target, p, value) {
        target[p] = value;
        return true;
      },
      get(target, p) {
        return target[p] || rawWindow[p];
      },
      has(target, p) {
        return p in target || p in rawWindow;
      }
    });
  }

  active() {
    this.sandboxRunning = true;
  }

  inactive() {
    this.sandboxRunning = false;
  }
}

// 使用示例
const sandbox1 = new ProxySandbox();
const sandbox2 = new ProxySandbox();

((window) => {
  window.a = 'sandbox1';
  console.log(window.a); // sandbox1
})(sandbox1.proxy);

((window) => {
  window.a = 'sandbox2';
  console.log(window.a); // sandbox2
})(sandbox2.proxy);

console.log(window.a); // undefined - 真实的 window 没有被污染

start({
  sandbox: {
    strictStyleIsolation: true
  }
});

function strictStyleIsolation(container) {
  if (!container.shadowRoot) {
    const shadow = container.attachShadow({ mode: 'open' });
    // 将子应用内容移到 Shadow DOM 中
    while (container.firstChild) {
      shadow.appendChild(container.firstChild);
    }
  }
}

start({
  sandbox: {
    experimentalStyleIsolation: true
  }
});

function scopedCSS(css, appName) {
  const prefix = `div[data-qiankun="${appName}"]`;

  return css.replace(/^([\s\S]*){/gm, (match) => {
    return match.replace(/^([^{]+){/, (selectors) => {
      return selectors.replace(/([^,]+)(,|$)/g, (item, selector, comma) => {
        // 处理各种选择器
        if (selector.includes(':root') || selector.includes('body')) {
          return `${prefix} ${selector.replace(/:root|body/g, '')}${comma}`;
        }
        return `${prefix} ${selector.trim()}${comma}`;
      });
    });
  });
}

// 1. 获取子应用 HTML
const html = await fetch(entry).then(res => res.text());

// 2. 解析 HTML，提取资源
const { template, scripts, styles, entry } = importHTML(html);

// 3. 处理 CSS - 内联化
const embedHTML = await getEmbedHTML(template, styles);

// 4. 执行 JS - 沙箱化执行
const execScripts = () => {
  return getExternalScripts(scripts).then(scriptTexts => {
    return scriptTexts.map((scriptText, index) => {
      return execScripts(scriptText, proxy);
    });
  });
};

// 5. 获取生命周期
const lifecycle = await execScripts();

// 主应用 main.js
import WujieVue from 'wujie-vue';

// 设置子应用默认配置
WujieVue.setupApp({
  name: 'vue3-app',
  url: 'http://localhost:7300/',
  exec: true,        // 预执行
  alive: true,       // 子应用保活
  props: {
    data: '主应用传入的数据'
  }
});

// 启动
WujieVue.start();

// Vue3 子应用入口 main.js
let instance;

// 独立运行
if (!window.__WUJIE) {
  createApp(App).use(router).mount('#app');
}

// 导出生命周期（可选，保活模式需要）
export async function bootstrap(app) {
  console.log('子应用 bootstrap');
}

export async function mount(app) {
  instance = createApp(App);
  instance.use(router);
  instance.mount('#app');
}

export async function unmount(app) {
  instance?.unmount();
}

// 创建纯净的 iframe
function createIframe() {
  const iframe = document.createElement('iframe');
  iframe.setAttribute('style', 'display: none');
  // 关键：设置为同域，便于通信
  iframe.src = 'about:blank';
  document.body.appendChild(iframe);

  const iframeWindow = iframe.contentWindow;
  const iframeDocument = iframeWindow.document;

  // 写入空文档
  iframeDocument.open();
  iframeDocument.write('<!DOCTYPE html><html><head></head><body></body></html>');
  iframeDocument.close();

  return { iframe, iframeWindow, iframeDocument };
}

// 创建 WebComponent 容器
function createShadowRoot(host) {
  const shadowRoot = host.attachShadow({ mode: 'open' });
  return shadowRoot;
}

// 将子应用 DOM 插入 Shadow DOM
function renderApp(shadowRoot, html) {
  shadowRoot.innerHTML = html;
}

// 代理 iframe 中的 document 操作指向 Shadow DOM
function patchDocument(iframeWindow, shadowRoot) {
  const proxyDocument = new Proxy(iframeWindow.document, {
    get(target, prop) {
      // 代理 DOM 查询方法
      if (['querySelector', 'querySelectorAll', 'getElementById'].includes(prop)) {
        return function(...args) {
          return shadowRoot[prop](...args);
        };
      }
      // 代理 body 和 head
      if (prop === 'body' || prop === 'head') {
        return shadowRoot.querySelector(prop);
      }
      return target[prop];
    }
  });

  iframeWindow.document = proxyDocument;
}

// 劫持 iframe 的 history.pushState
function syncPath(iframeWindow, appName) {
  const originalPushState = iframeWindow.history.pushState;
  const originalReplaceState = iframeWindow.history.replaceState;

  iframeWindow.history.pushState = function(...args) {
    const [state, title, path] = args;
    // 将子应用路径同步到主应用 URL 参数
    const mainAppUrl = new URL(window.location.href);
    mainAppUrl.searchParams.set(`${appName}_path`, path);
    window.history.replaceState(state, title, mainAppUrl.toString());

    return originalPushState.apply(this, args);
  };

  // 初始化时恢复路由
  const mainAppUrl = new URL(window.location.href);
  const subAppPath = mainAppUrl.searchParams.get(`${appName}_path`);
  if (subAppPath) {
    iframeWindow.history.replaceState(null, '', subAppPath);
  }
}

// 主应用 main.js
import microApp from '@micro-zoe/micro-app';

// 启动
microApp.start({
  // 全局配置
  'shadowDOM': true,          // 使用 shadow DOM
  'destroy': false,           // 不销毁子应用（保活）
  'inline': true,             // 使用 inline 模式
  'iframe': true,             // 使用 iframe 沙箱（兼容 vite）
});

// 主应用
import { initGlobalState } from 'qiankun';

const { onGlobalStateChange, setGlobalState } = initGlobalState({
  user: { name: 'Alice', role: 'admin' },
  token: 'xxx'
});

// 监听变化
onGlobalStateChange((state, prev) => {
  console.log('State changed:', state, prev);
});

// 子应用
export async function mount(props) {
  // 获取状态
  console.log(props.getGlobalState());

  // 监听状态变化
  props.onGlobalStateChange((state, prev) => {
    console.log('[子应用] state changed:', state);
  });

  // 更新状态
  props.setGlobalState({ user: { name: 'Bob' } });
}

// 主应用
import { bus } from 'wujie';

// 监听事件
bus.$on('data-change', (data) => {
  console.log('收到数据:', data);
});

// 发送事件
bus.$emit('data-change', { message: 'Hello from main' });

// 子应用
window.$wujie.bus.$on('data-change', (data) => {
  console.log('子应用收到:', data);
});

window.$wujie.bus.$emit('data-change', { from: 'subapp' });

// 子应用
const mainApp = window.parent;

// 发送消息
mainApp.postMessage({
  type: 'subapp-message',
  data: { message: 'Hello' }
}, '*');

// 主应用
window.addEventListener('message', (event) => {
  if (event.data.type === 'subapp-message') {
    console.log('收到子应用消息:', event.data);
  }
});

// 主应用
<WujieVue
  name="subapp"
  :props="{ user: userInfo, actions: mainActions }"
/>

// 子应用
const props = window.$wujie.props;
console.log(props.user);  // { name: 'Alice', ... }
props.actions.someMethod();  // 调用主应用方法

// 主应用劫持路由变化
function routeChange() {
  const currentPath = window.location.pathname;

  // 匹配子应用路由规则
  if (currentPath.startsWith('/app1')) {
    // 激活 app1
    loadApp('app1', currentPath);
  } else if (currentPath.startsWith('/app2')) {
    // 激活 app2
    loadApp('app2', currentPath);
  }
}

// 监听路由变化
window.addEventListener('popstate', routeChange);
window.addEventListener('hashchange', routeChange);

// 将子应用路径存储在 URL 参数中
function syncSubAppPath(appName, path) {
  const url = new URL(window.location.href);
  url.searchParams.set(`${appName}_path`, path);
  window.history.replaceState(null, '', url.toString());
}

// 恢复子应用路径
function restoreSubAppPath(appName) {
  const url = new URL(window.location.href);
  const path = url.searchParams.get(`${appName}_path`);
  return path || '/';
}

// 示例：
// 主应用 URL: https://main.com/?app1_path=/dashboard&app2_path=/settings

// qiankun 预加载
start({
  prefetch: 'all',  // 预加载所有子应用
  // prefetch: ['app1', 'app2'],  // 预加载指定子应用
  // prefetch: true,  // 预加载剩余子应用
});

// wujie 预加载
WujieVue.preloadApp({
  name: 'vue-app',
  url: 'http://localhost:7300/'
});

// 预执行可以在浏览器空闲时执行子应用 JS
WujieVue.setupApp({
  name: 'vue-app',
  url: 'http://localhost:7300/',
  exec: true  // 启用预执行
});

// Fiber 模式：分段执行，避免阻塞主线程
WujieVue.setupApp({
  name: 'vue-app',
  url: 'http://localhost:7300/',
  fiber: true  // 使用 requestIdleCallback 分段执行
});

// 主应用：导出公共依赖
import antd from 'antd';
import lodash from 'lodash';

window.sharedLibs = {
  antd,
  lodash
};

// 子应用：webpack 配置 external
module.exports = {
  externals: {
    'antd': 'root.sharedLibs.antd',
    'lodash': 'root.sharedLibs.lodash'
  }
};

// 1. 导出生命周期函数
export async function bootstrap() {}
export async function mount(props) {}
export async function unmount(props) {}

// 2. 配置 public-path
if (window.__POWERED_BY_QIANKUN__) {
  __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;
}

// 3. 配置 CORS
devServer: {
  headers: {
    'Access-Control-Allow-Origin': '*'
  }
}

// 4. 配置 webpack output
output: {
  library: `${name}-[name]`,
  libraryTarget: 'umd',
  globalObject: 'window'
}

// 1. 路由适配
function render(props = {}) {
  const { container } = props;
  router = createRouter({
    base: window.__POWERED_BY_QIANKUN__ ? '/app/' : '/',
    mode: 'history'
  });
}

// 2. 请求适配
axios.defaults.baseURL = window.__POWERED_BY_QIANKUN__
  ? '/api/proxy'
  : '/api';

// 3. 全局样式适配
// 避免使用全局 body、html 选择器
// 使用 scoped 或 CSS Modules

// webpack 配置
module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          priority: 10
        }
      }
    }
  }
};

// 策略1：预加载所有子应用
start({ prefetch: 'all' });

// 策略2：预加载剩余子应用
start({ prefetch: true });

// 策略3：手动指定预加载
start({ prefetch: ['app1', 'app3'] });

// 策略4：智能预加载（根据用户行为）
const userBehavior = analyzeUserBehavior();
const likelyApps = predictNextApps(userBehavior);
start({ prefetch: likelyApps });

// Service Worker 缓存
self.addEventListener('fetch', (event) => {
  const url = new URL(event.request.url);

  // 缓存子应用资源
  if (url.pathname.startsWith('/micro-app/')) {
    event.respondWith(
      caches.match(event.request).then((response) => {
        return response || fetch(event.request).then((fetchResponse) => {
          return caches.open('micro-app-cache').then((cache) => {
            cache.put(event.request, fetchResponse.clone());
            return fetchResponse;
          });
        });
      })
    );
  }
});

// 全局错误捕获
window.addEventListener('error', (event) => {
  console.error('全局错误:', event.error);
  // 上报错误
  reportError({
    type: 'global-error',
    message: event.error?.message,
    stack: event.error?.stack,
    app: currentApp
  });
});

// Promise 错误捕获
window.addEventListener('unhandledrejection', (event) => {
  console.error('Promise 错误:', event.reason);
  reportError({
    type: 'promise-error',
    reason: event.reason,
    app: currentApp
  });
});

// qiankun 生命周期错误处理
registerMicroApps([
  {
    name: 'app1',
    entry: '...',
    container: '#container',
    activeRule: '/app1',
    errorBoundary(err) {
      console.error('子应用错误:', err);
      // 渲染错误页面
      renderErrorPage(err);
    }
  }
]);

// 开发环境配置
const isDev = process.env.NODE_ENV === 'development';

registerMicroApps([
  {
    name: 'app1',
    entry: isDev
      ? 'http://localhost:7100'  // 本地开发地址
      : 'https://app1.example.com',  // 生产地址
    container: '#container',
    activeRule: '/app1'
  }
]);

// qiankun 开发模式
start({
  sandbox: {
    strictStyleIsolation: false  // 开发时关闭严格隔离，便于调试
  }
});

// 在子应用中添加调试标记
if (process.env.NODE_ENV === 'development') {
  window.__SUB_APP_NAME__ = 'app1';
  window.__SUB_APP_VERSION__ = '1.0.0';
}

// 在控制台中快速定位
console.log(
  '%c%s',
  'background: #ff006e; color: white; padding: 4px;',
  `[${window.__SUB_APP_NAME__}] 子应用日志`
);