# Xuanji
**Repository Path**: ereddate2017/xuanji
## Basic Information
- **Project Name**: Xuanji
- **Description**: 一个轻量级、灵活且功能强大的通用型微前端框架，如古代天文观测仪器「璇玑」一般，让多个独立应用既各自运转又协同工作，支持应用的独立开发、独立部署、运行时动态加载以及应用间的通信与路由管理等核心微前端特性。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-12
- **Last Updated**: 2025-11-16
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 璇玑微前端框架 (Xuanji)
一个轻量级、灵活且功能强大的通用型微前端框架，让多个独立应用既各自运转又协同工作，支持应用的独立开发、独立部署和动态加载。
## 🌟 核心功能特性
- **应用动态加载** - 按需加载子应用，提高初始加载性能
- **路由管理** - 基于路径的智能应用激活机制
- **应用间通信** - 安全高效的事件总线系统
- **样式隔离** - 多种隔离策略（CSS命名空间、Shadow DOM）防止样式冲突
- **JavaScript沙箱** - 运行时隔离，保护主应用安全
- **框架无关** - 完美支持React、Vue、Angular等主流前端框架
- **增强资源加载** - 智能预加载、缓存管理和自定义加载策略
- **高级性能优化** - 代码分割、资源压缩和内存优化
- **可视化配置** - 配置生成工具简化应用集成流程
- **服务端渲染支持** - 完整的微应用SSR解决方案
- **插件系统** - 灵活的插件架构，内置10个核心插件，支持功能扩展和定制化
## 🔰 从零开始使用指南
### 步骤 1: 安装框架
```bash
# 使用npm
npm install xuanji-microfrontend
# 使用yarn
yarn add xuanji-microfrontend
# 或者直接引入CDN
```
### 步骤 2: 创建主应用
创建一个简单的HTML页面作为主应用容器：
```html
璇玑微前端主应用
```
创建主应用的配置文件：
```javascript
// main.js
// 如果使用CDN方式引入
const { registerApplication, start } = window.xuanji;
// 注册子应用
registerApplication({
name: 'app1',
activeWhen: '/app1', // 当路径匹配'/app1'时激活此应用
container: '#app1-container', // 挂载容器
loadApp: () => import('./app1/index.js'), // 动态加载子应用
isolationStrategy: 'css_namespace', // 启用CSS命名空间隔离
preload: true // 启用预加载
});
// 注册第二个子应用
registerApplication({
name: 'app2',
activeWhen: '/app2',
container: '#app2-container',
loadApp: () => import('./app2/index.js')
});
// 启动微前端框架
start();
```
### 步骤 3: 创建第一个子应用
```javascript
// app1/index.js
const app = {
// 应用初始化，只执行一次
bootstrap: () => {
console.log('App1 初始化');
return Promise.resolve();
},
// 应用挂载
mount: (props) => {
const { container } = props;
container.innerHTML = 'Hello from App 1!
';
},
// 应用卸载
unmount: () => {
console.log('App1 卸载');
// 在这里清理资源
}
};
// 允许子应用独立运行的逻辑
if (!window.xuanji) {
// 直接挂载应用
document.addEventListener('DOMContentLoaded', () => {
const container = document.querySelector('#app1-container') || document.body;
app.bootstrap().then(() => app.mount({ container }));
});
}
export default app;
```
### 步骤 4: 创建第二个子应用
```javascript
// app2/index.js
const app = {
bootstrap: () => {
console.log('App2 初始化');
return Promise.resolve();
},
mount: (props) => {
const { container } = props;
container.innerHTML = 'Hello from App 2!
';
},
unmount: () => {
console.log('App2 卸载');
}
};
if (!window.xuanji) {
document.addEventListener('DOMContentLoaded', () => {
const container = document.querySelector('#app2-container') || document.body;
app.bootstrap().then(() => app.mount({ container }));
});
}
export default app;
```
### 步骤 5: 运行应用
配置你的构建工具（如Webpack、Vite等）后，启动应用并访问：
- `http://localhost:3000/` - 查看主应用
- `http://localhost:3000/app1` - 查看并激活第一个子应用
- `http://localhost:3000/app2` - 查看并激活第二个子应用
## 🏗️ 使用框架模板快速创建微应用
如果你使用React、Vue或Angular，可以直接使用我们提供的模板快速创建微应用：
```bash
# 创建React微应用
npm create xuanji-microfrontend@latest my-react-app -- --template react
# 创建Vue微应用
npm create xuanji-microfrontend@latest my-vue-app -- --template vue
# 创建Angular微应用
npm create xuanji-microfrontend@latest my-angular-app -- --template angular
```
这些模板已经内置了：
- 与主应用的通信机制
- 路由集成
- 生命周期管理
- 性能监控
## 📱 实现框架集成微应用
### React微应用示例
```javascript
// react-app/index.js
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
const xuanjiApp = {
bootstrap: () => Promise.resolve(),
mount: (props) => {
const { container } = props;
ReactDOM.render(, container.querySelector('#root') || container);
},
unmount: (props) => {
const { container } = props;
ReactDOM.unmountComponentAtNode(container.querySelector('#root') || container);
}
};
// 独立运行时逻辑
if (!window.xuanji) {
ReactDOM.render(, document.getElementById('root'));
}
export default xuanjiApp;
```
### Vue微应用示例
```javascript
// vue-app/index.js
import Vue from 'vue';
import App from './App.vue';
let vm = null;
const xuanjiApp = {
bootstrap: () => Promise.resolve(),
mount: (props) => {
const { container } = props;
vm = new Vue({
render: h => h(App, { props })
}).$mount();
container.appendChild(vm.$el);
},
unmount: () => {
if (vm) {
vm.$destroy();
vm = null;
}
}
};
if (!window.xuanji) {
new Vue({ render: h => h(App) }).$mount('#app');
}
export default xuanjiApp;
```
## 📢 应用间通信
### 步骤 1: 在主应用中监听和发送事件
```javascript
// 通过CDN方式使用
const { registerApplication, start, eventBus, resourceManager, advancedPerformanceOptimizer } = window.xuanji;
// 监听子应用发送的事件
eventBus.on('app:message', (data) => {
console.log('收到子应用消息:', data);
});
// 向所有子应用发送消息
document.querySelector('#send-btn').addEventListener('click', () => {
eventBus.emit('main:notification', {
message: '这是来自主应用的通知'
});
});
```
### 步骤 2: 在子应用中监听和发送事件
```javascript
// app1/index.js
const app = {
mount: (props) => {
// 从props中获取eventBus
const { container, eventBus } = props;
// 显示UI
container.innerHTML = `
应用1
`;
// 监听主应用的通知
eventBus.on('main:notification', (data) => {
alert(`收到主应用通知: ${data.message}`);
});
// 发送消息到主应用
container.querySelector('#send-message').addEventListener('click', () => {
eventBus.emit('app:message', {
from: 'app1',
content: 'Hello from App1!'
});
});
},
unmount: (props) => {
// 清理事件监听
props.eventBus.off('main:notification');
}
};
export default app;
```
## ⚡ 启用性能优化
### 步骤 1: 配置资源加载策略
```javascript
// 在主应用中配置
import { resourceManager } from 'xuanji-microfrontend';
// 设置全局资源加载策略
resourceManager.setLoadingStrategy({
timeout: 10000, // 设置加载超时时间为10秒
useCache: true, // 启用资源缓存
cacheStrategy: 'memory', // 使用内存缓存
preload: {
enabled: true, // 启用预加载
delay: 500 // 空闲500ms后开始预加载
}
});
// 预加载一些共享资源
resourceManager.preloadResources([
{ type: 'script', url: '/assets/common.js' },
{ type: 'style', url: '/assets/common.css' }
]);
```
### 步骤 2: 启用高级性能优化
```javascript
// 在主应用中启用
import { advancedPerformanceOptimizer } from 'xuanji-microfrontend';
// 执行综合性能优化，包含代码分割和内存优化
advancedPerformanceOptimizer.optimizeApp({
name: 'main-app',
codeSplitting: {
splitModules: [
{
name: 'dashboard',
loadFunction: () => import('./components/Dashboard'),
dependencies: []
}
],
preloadModules: ['dashboard']
},
lazyLoading: {
lazyElements: [
{ selector: '.lazy-section', loader: () => import('./components/LazySection') }
]
},
caching: {
cacheOptions: {
defaultTTL: 3600000, // 1小时
preheatCache: []
}
}
});
```
## 🛠️ 使用配置生成器
### 方式 1: 编程方式生成配置
```javascript
import { configGenerator } from 'xuanji-microfrontend';
// 使用模板生成React应用配置
const reactAppConfig = configGenerator.generateFromTemplate('react', {
name: 'my-react-app',
activeWhen: '/react',
container: '#react-container',
loadApp: () => import('./react-app/index.js')
});
// 验证配置是否正确
const isValid = configGenerator.validateConfig(reactAppConfig);
if (isValid) {
// 注册应用
xuanji.registerApp(reactAppConfig);
}
```
### 方式 2: 在React应用中使用可视化配置界面
```javascript
import { ConfigGeneratorUI } from 'xuanji-microfrontend/ui';
function AdminPanel() {
// 当配置生成后处理配置
const handleConfigGenerated = (config) => {
// 可以保存到配置文件或直接注册应用
console.log('生成的配置:', config);
// xuanji.registerApp(config);
};
return (
微应用配置生成器
);
}
```
## 🔒 启用应用隔离
### CSS隔离
在注册应用时配置样式隔离策略：
```javascript
xuanji.registerApp({
name: 'app1',
activeWhen: '/app1',
container: '#app1-container',
loadApp: () => import('./app1/index.js'),
// 选择CSS隔离策略
isolationStrategy: 'css_namespace' // 或 'shadow_dom' 或 'none'
});
```
### JavaScript沙箱
为不信任的第三方应用启用JS沙箱：
```javascript
xuanji.registerApp({
name: 'third-party-app',
activeWhen: '/third-party',
container: '#third-party-container',
loadApp: () => import('./third-party-app/index.js'),
// 启用JS沙箱
jsSandbox: true,
// 启用严格模式
strictMode: true
});
```
## 🔄 服务端渲染支持
如需在服务端渲染微应用，请参考[SSR管理器文档](./docs/SSRManagerGuide.md)获取详细配置步骤。
## 📝 完整功能文档
- [快速开始指南](./docs/QuickStart.md) - 详细的安装和基础使用说明
- [技术架构文档](./docs/TechnicalArchitecture.md) - 框架核心实现细节和技术亮点
- [模块关系分析](./docs/ModuleRelationshipAnalysis.md) - 框架各模块间的依赖关系和调用流程
- [插件系统对比](./docs/PluginSystemComparison.md) - 微前端框架插件系统详细对比分析
- [测试与质量保证](./docs/TestingAndQualityAssurance.md) - 微应用的测试策略和质量保障措施
- [新功能使用指南](./docs/NewFeaturesGuide.md) - 增强的资源加载策略、性能优化和配置工具的详细文档
- [React集成指南](./docs/ReactIntegrationGuide.md) - React微应用的最佳实践
- [Vue集成指南](./docs/VueIntegrationGuide.md) - Vue微应用的最佳实践
- [Angular集成指南](./docs/AngularIntegrationGuide.md) - Angular微应用的最佳实践
- [API参考文档](./docs/API.md) - 完整的API文档
## 🚀 示例代码
- [集成示例](./examples/integration-examples.js) - 各种框架的集成示例
- [性能优化示例](./examples/performance-optimization-examples.js) - 性能优化功能的使用示例
- [通信示例](./examples/communicationExample.js) - 应用间通信示例
## 🛠️ 开发与构建
```bash
# 安装依赖
npm install
# 开发模式启动
npm run dev
# 构建生产版本
npm run build
```
## 🤝 贡献指南
欢迎贡献代码！请遵循以下流程：
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启 Merge Request
## 📄 许可证
MIT License