TencentBlueKing/bk-weweb

BK-WeWeb 微前端框架

BK-WeWeb 是腾讯蓝鲸团队开源的轻量级微前端框架，基于 Web Components 技术，支持微应用和微模块两种模式。

快速开始

安装

npm install @blueking/bk-weweb

在主应用中引入

// main.ts
import '@blueking/bk-weweb';

两种运行模式

| 模式 | 说明 | 入口类型 | 适用场景 | | ---------------- | ---------------- | -------- | ------------------ | | 微应用 (app) | 加载完整远程应用 | HTML | 独立部署的完整应用 | | 微模块 (js) | 加载远程 JS 模块 | JS | 远程组件、插件系统 |

基础用法

Web Component 标签方式

<template>
  <!-- 微应用 -->
  <bk-weweb
    id="child-app"
    url="http://localhost:8001/"
    :scope-js="true"
    :scope-css="true"
  />

  <!-- 微模块 -->
  <bk-weweb
    id="chart-module"
    mode="js"
    url="http://localhost:8002/widget.js"
  />
</template>

Hooks API 方式

import { loadApp, mount, unmount } from '@blueking/bk-weweb';

// 加载并挂载微应用
await loadApp({
  url: 'http://localhost:8001/',
  id: 'my-app',
  scopeJs: true,
  scopeCss: true,
  data: { userId: '123', token: 'xxx' },
});
mount('my-app', document.getElementById('container'));

// 卸载
unmount('my-app');

核心 API

生命周期 Hooks

| API | 说明 | | ----------------------------------------- | ---------------------------------------------- | | loadApp(props) | 加载微应用，返回 Promise<MicroAppModel> | | loadInstance(props) | 加载微模块，返回 Promise<MicroInstanceModel> | | mount(appKey, container?, callback?) | 挂载到容器 | | unmount(appKey) | 卸载应用/模块 | | activated(appKey, container, callback?) | 激活（用于 keepAlive 模式） | | deactivated(appKey) | 停用（用于 keepAlive 模式） | | unload(url) | 删除缓存 |

预加载 Hooks

| API | 说明 | | --------------------------- | -------------- | | preLoadApp(options) | 预加载微应用 | | preLoadInstance(options) | 预加载微模块 | | preLoadSource(sourceList) | 预加载资源文件 |

启动配置

import weWeb from '@blueking/bk-weweb';

weWeb.start({
  collectBaseSource: true, // 收集主应用资源供子应用共享
  webComponentTag: 'my-micro-app', // 自定义标签名
  fetchSource: async (url, options) => {
    // 自定义资源获取（如添加认证头）
    const response = await fetch(url, {
      ...options,
      headers: { Authorization: `Bearer ${token}` },
    });
    return response.text();
  },
});

配置属性速查

微应用属性 (mode="app" 或默认)

| 属性 | 类型 | 默认值 | 说明 | | ---------------- | --------------- | ------- | ---------------------- | | url | string | - | 必填，应用入口 URL | | id | string | - | 应用唯一标识符 | | scopeJs | boolean | true | JS 沙箱隔离 | | scopeCss | boolean | true | CSS 样式隔离 | | scopeLocation | boolean | false | 路由隔离 | | setShadowDom | boolean | false | 使用 Shadow DOM | | keepAlive | boolean | false | 缓存模式 | | showSourceCode | boolean | false | 显示源码 | | data | object/string | - | 传递数据 | | initSource | string[] | - | 初始化资源 |

微模块属性 (mode="js")

| 属性 | 类型 | 默认值 | 说明 | | ---------------- | --------------- | ------- | ---------------------- | | url | string | - | 必填，JS 模块 URL | | id | string | - | 必填，模块唯一标识 | | mode | 'js' | - | 必填，设为 'js' | | scopeJs | boolean | false | JS 沙箱隔离 | | scopeCss | boolean | true | CSS 样式隔离 | | keepAlive | boolean | false | 缓存模式 | | showSourceCode | boolean | true | 显示源码 | | data | object/string | - | 传递数据 |

子应用开发

全局变量

子应用中可通过以下全局变量获取运行时信息：

if (window.__POWERED_BY_BK_WEWEB__) {
  const appKey = window.__BK_WEWEB_APP_KEY__; // 应用标识
  const data = window.__BK_WEWEB_DATA__; // 主应用传递的数据
  const realWindow = window.rawWindow; // 原始 window
  const realDocument = window.rawDocument; // 原始 document
}

微模块 render 规范

微模块需导出包含 render 方法的对象：

// widget.js
export default {
  render(container: HTMLElement, data: Record<string, unknown>) {
    container.innerHTML = `<div>Hello ${data.name}</div>`;

    // 返回销毁函数
    return () => {
      container.innerHTML = '';
    };
  },

  // 可选：其他方法供主应用调用
  update(newData) {
    /* ... */
  },
  getState() {
    return {
      /* ... */
    };
  },
};

框架集成示例

Vue 3

<script setup lang="ts">
  import { ref, onMounted, onBeforeUnmount } from 'vue';
  import { loadApp, mount, unmount } from '@blueking/bk-weweb';

  const containerRef = ref<HTMLElement>();
  const appId = 'child-app';

  onMounted(async () => {
    await loadApp({
      url: 'http://localhost:8001/',
      id: appId,
      scopeJs: true,
      scopeCss: true,
      data: { userId: '123' },
    });
    mount(appId, containerRef.value!);
  });

  onBeforeUnmount(() => unmount(appId));
</script>

<template>
  <div
    ref="containerRef"
    class="app-container"
  ></div>
</template>

React

import { useRef, useEffect } from 'react';
import { loadApp, mount, unmount } from '@blueking/bk-weweb';

const MicroApp: React.FC = () => {
  const containerRef = useRef<HTMLDivElement>(null);
  const appId = 'child-app';

  useEffect(() => {
    const load = async () => {
      await loadApp({
        url: 'http://localhost:8001/',
        id: appId,
        scopeJs: true,
        scopeCss: true,
      });
      if (containerRef.current) {
        mount(appId, containerRef.current);
      }
    };
    load();
    return () => unmount(appId);
  }, []);

  return (
    <div
      ref={containerRef}
      style={{ height: '600px' }}
    />
  );
};

预加载策略

import { preLoadApp, mount } from '@blueking/bk-weweb';

// 页面加载完成后预加载
window.addEventListener('load', () => {
  setTimeout(() => {
    preLoadApp({
      url: 'http://localhost:8001/',
      id: 'dashboard',
      scopeJs: true,
    });
  }, 2000); // 延迟避免影响首屏
});

// 需要时直接挂载（无需等待加载）
function showDashboard() {
  mount('dashboard', document.getElementById('container'));
}

常见问题

1. 子应用加载失败

• 检查 CORS 配置，确保允许跨域
• 检查 URL 是否正确
• 查看控制台错误信息

2. 样式冲突

• 确认 scopeCss 已开启
• 考虑使用 setShadowDom 获得更彻底隔离
• 检查是否使用了 !important

3. 子应用路由不工作

• 开启 scopeLocation 实现路由隔离
• 确认路由模式（hash/history）

4. 访问主应用全局变量

// 子应用中访问真实 window
const realWindow = window.rawWindow || window;
const mainConfig = realWindow.__MAIN_APP_CONFIG__;

详细参考文档

• Hooks API 详解
• 微应用配置
• 微模块配置

类型定义

import {
  loadApp,
  loadInstance,
  mount,
  unmount,
  activated,
  deactivated,
  unload,
  preLoadApp,
  preLoadInstance,
  preLoadSource,
  WewebMode,
  type IAppModelProps,
  type IJsModelProps,
  type BaseModel,
} from '@blueking/bk-weweb';