1. 环境准备与总体架构设计
1.1 明确目标与边界
在正式实施前，必须明确目标需求与边界条件。本文聚焦在在 Java 项目中如何集成 qiankun 微前端？完整实操指南，目标是通过基座应用统一路由、权限与全局状态，将多个前端子应用独立开发、独立部署，同时实现运行时组合与资源隔离。边界条件包括：微应用的技术栈可以是 Vue、React、或其他框架，但基座应用应具备唯一入口、统一上下文和错误降级能力。
为确保后续开发的顺畅，还需明确关键原则：沙箱隔离、路由隔离、资源隔离，并通过后端 Java 服务进行静态资源提供与安全控制。只有在这些边界内，才可能实现稳定的微前端体验。
1.2 技术选型与版本规划
在 Java 项目中集成 qiankun，常见做法是把前端基座作为一个独立前端项目，与各自的微应用分开开发、打包后部署到同一个 Java 服务的静态资源目录。Qiankun 的核心能力是注册微应用、切换、沙箱与生命周期回调，因此版本选择应兼顾生态活跃度与兼容性。
建议优先选择稳定版本，结合现有前端框架的生态。如果你使用 Vue、React 或其他框架，确保微应用的打包输出能够被基座应用按入口地址正确加载。以下是一个基础的版本选择清单：qiankun、Vue/React、Webpack/Vite 的兼容性与打包产物输出路径需要在初期就确定。
# 安装 qiankun（示例，基座应用需依赖）
npm install qiankun --save
2. Java 项目中前端资源组织与入口设计
2.1 静态资源放置位置与访问路径
Java 后端通常通过静态资源服务来提供前端产物。为确保 qiankun 基座与微应用解耦，建议将基座页面与微应用产物放在统一的静态资源目录下，便于后续在 Spring Boot 等框架中进行静态资源映射。静态资源路径的明确，是后续跨域、路由重写与资源加载的基础。
在实际部署时，可以将打包输出的 dist 目录放入资源根目录下，例如 classpath:/static/ 或 /public/，并通过 Spring 的资源映射进行访问。一致的资源定位将降低路径错配的风险。
// Spring Boot 示例：将前端打包产物放到 static 目录
// 目录结构：src/main/resources/static/
// 访问示例：http://localhost:8080/index.html
2.2 基座入口设计与路由结构
基座应用需要一个统一的入口页面来加载 qiankun 的路由与微应用入口。将入口页面设计为可独立上线的静态文件，并通过前端路由管理微应用的激活规则。入口设计要确保首屏加载时间短、首屏渲染稳定。
在路由层面，基座应具备 以下能力：注册微应用、触发加载、切换页面、捕获全局事件，并对不可用微应用做降级处理。下面的示例展示了一个简单的入口结构和入口脚本的定位方式。
<!-- index.html（基座入口） -->
<!DOCTYPE html>
<html>
<head><meta charset="UTF-8"><title>基座应用</title>
</head>
<body><div id="root"></div><script src="/static/js/qiankun-base.js"></script>
</body>
</html>
// 基座入口逻辑（示例）
// 通过 qiankun 注册微应用，绑定到特定容器与激活规则
import { registerMicroApps, start } from 'qiankun';const apps = [{ name: 'vueApp', entry: '/static/vue-app/', container: '#micro-container', activeRule: '/vue' },{ name: 'reactApp', entry: '/static/react-app/', container: '#micro-container', activeRule: '/react' }
];registerMicroApps(apps, {beforeLoad: (app) => console.log('Will load', app.name),beforeMount: (app) => console.log('Will mount', app.name),afterUnmount: (app) => console.log('App unmounted', app.name)
});start({ prefetch: true, sandbox: { strictStyleIsolation: true } });
3. qiankun 环境搭建与依赖安装
3.1 安装 qiankun 并确定打包输出
在基座应用项目中，确保安装 qiankun 并配置打包流程，使得微应用的产物能够以独立入口形式提供。安装 qiankun 是核心第一步，后续的微应用注册、沙箱配置与生命周期管理都以此为基础。
同时需要确认微应用的打包输出目录与基座的静态资源映射一致，避免跨域请求时的路径错位。打包产物应对外暴露可直接访问的入口。
# 安装 qiankun（基座应用）
npm install qiankun --save
3.2 选择打包工具与静态资源代理
可以根据前端框架选择 Vue/React 的默认打包工具（如 Vue CLI、Vite、CRA）并输出 dist 目录。为方便在 Java 后端直接提供静态资源，建议开启开发阶段的代理以实现跨域调试，同时在生产阶段使用静态资源服务器。代理与代理策略应在开发阶段尽量统一，避免上线阶段的路径差异。
# 以 Vite 为例，开发阶段通过代理访问后端 API
# vite.config.js
export default {server: {proxy: {'/api': 'http://localhost:8080'}}
}
4. 基座应用配置与注册微应用
4.1 注册微应用
注册微应用是 qiankun 的核心步骤。通过定义 name、entry、container、activeRule 等字段，基座即可在用户切换路由时加载相应的微应用。准确的 activeRule 能确保子应用在正确时机被挂载。
在 Java 项目中，微应用的入口可以是静态资源中的静态页面，也可以来自外部地址。确保跨域策略在生产环境中可控，避免在加载时遇到权限问题。注册信息需要与前端路由规则对齐。
import { registerMicroApps, start } from 'qiankun';const microApps = [{ name: 'vueProduct', entry: '/static/vue-product/', container: '#subapp-viewport', activeRule: '/vue-product' },{ name: 'reactAnalytics', entry: '//localhost:3001/', container: '#subapp-viewport', activeRule: '/analytics' }
];registerMicroApps(microApps, {beforeMount: [app => console.log('Before mount', app.name)]
});
4.2 启动生命周期与路由切换
定义生命周期钩子，可以在微应用加载、挂载、卸载等阶段执行自定义逻辑，例如日志、权限验证、全局事件总线的更新等。生命周期钩子使跨应用协作更可控。
启动时可以通过配置参数对沙箱、预取、以及错误降级等行为做细粒度控制。启动参数应在上线前透传并测试。
start({ prefetch: true, sandbox: { strictStyleIsolation: true, experimentalStyleIsolation: true } });
5. 微应用开发、打包与对接
5.1 子应用独立打包与入口暴露
子应用应具备独立的开发、打包与部署能力，产物通常暴露一个入口 HTML 页或单独的静态资源入口。将子应用构建输出放置到基座应用可访问的目录下，确保在 entry 指定的地址能正确加载。独立打包提升了微应用的迭代效率。
子应用需要遵循微前端约定：提供统一的接口、尽量使用沙箱进行样式隔离，避免对基座全局样式造成污染。统一接口和沙箱策略是稳定运行的关键。
// 子应用示例（Vue/React）打包后输出 dist
// 构建命令在子应用工程中执行
npm run build
5.2 跨域、资源加载与样式隔离
由于微应用在不同域名或端口下运行时需要跨域资源加载，务必在开发阶段配置好代理与 CORS。基座域名应允许微应用通过安全通道加载资源。样式隔离通过沙箱来实现，降低样式冲突的概率。
常见做法包括：为微应用提供独立的域名或路径、将全局样式限定在沙箱作用域内，以及在打包阶段开启 CSS 模块化或 Shadow DOM。这些措施是提升用户体验和稳定性的关键。
6. 与后端 Java 服务的集成点与部署
6.1 资源路径映射与静态资源服务
后端需要将前端产物映射为静态资源服务。通过 Java 配置将静态资源目录暴露给前端基座应用与子应用，确保它们的入口地址可以直接被浏览器请求。资源路径映射是前后端协作的桥梁。
示例中，利用 Spring 的资源处理器将 /static 路径映射到 classpath:/static/，以便基座能够正确加载 index.html 与微应用的 dist 内容。一致的资源路径能减少部署时的错配。
@Configuration
public class WebConfig implements WebMvcConfigurer {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");}
}
6.2 CORS、认证与安全策略
微应用间的跨域请求需要合适的 CORS 配置，尤其是在跨域加载微应用的静态资源时。后端应对前端请求进行必要的身份校验与跨域许可，避免影响基座的路由体验。严格的跨域策略能提升系统安全性。
还可以通过在基座应用中集中处理认证与授权，将凭证信息通过 qiankun 的 props 传递给微应用，确保各微应用具备所需的上下文。统一认证上下文是简化前端状态管理的有效手段。
@Bean
public CorsConfigurationSource corsConfigurationSource() {CorsConfiguration config = new CorsConfiguration();config.addAllowedOrigin("http://localhost:5173"); // 前端基座域名config.setAllowedMethods(Arrays.asList("GET","POST","PUT","DELETE"));config.setAllowCredentials(true);UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();source.registerCorsConfiguration("/**", config);return source;
}
7. 调试、监控与性能优化
7.1 调试微应用加载与路由切换
在调试阶段，应关注微应用的加载时间、路由切换时机以及沙箱对样式的影响。浏览器控制台和网络面板是第一线工具，结合 qiankun 的生命周期回调，可以快速定位问题。实时日志与生命周期钩子是排错的关键。
可通过在注册微应用时加入 beforeLoad、beforeMount、afterUnmount 等钩子，输出关键信息，结合浏览器的性能分析工具进行追踪。有序的日志输出能大幅降低排错成本。
// 基座日志增强
registerMicroApps(apps, {beforeLoad: (app) => console.log('[Qiankun] loading', app.name),beforeMount: (app) => console.log('[Qiankun] mounting', app.name),afterUnmount: (app) => console.log('[Qiankun] unmounted', app.name)
});
7.2 性能优化、预加载与缓存策略
性能优化的核心在于减少首屏加载、提升微应用切换速度，以及合理利用缓存。开启预加载（prefetch）可以在用户实际切换前就把部分微应用资源加载就绪，但要避免占用过多带宽。结合网络环境和用户行为调整预取策略。
此外，针对常用微应用可以采用缓存策略，避免重复初始化成本。通过沙箱隔离与样式封装，确保性能提升不会带来全局样式冲突。缓存策略与沙箱策略需共同评估。
start({ prefetch: 'all', sandbox: { strictStyleIsolation: true } });
