## File: README.md
# qiankun（乾坤）
> [!WARNING]
>
> 🚧 qiankun 3.0 is currently under active development — check out the [Roadmap](https://github.com/umijs/qiankun/discussions/1378) for details. Looking for qiankun 2.x? Its documentation lives at [v2.qiankun.umijs.org](https://v2.qiankun.umijs.org).
> In Chinese, `qian(乾)` means heaven and `kun(坤)` earth. `qiankun` is the universe.
Qiankun enables you and your teams to build next-generation and enterprise-ready web applications leveraging [Micro Frontends](https://micro-frontends.org/). It is inspired by and based on [single-spa](https://github.com/single-spa/single-spa).
## 🤔 Motivation
A quick recap about the concept of `Micro Frontends`:
> Techniques, strategies and recipes for building a **modern web app** with **multiple teams** using **different JavaScript frameworks**. — [Micro Frontends](https://micro-frontends.org/)
Qiankun was birthed internally in our group during the time web app development by distributed teams had turned to complete chaos. We faced every problem micro frontend was conceived to solve, so naturally, it became part of our solution.
The path was never easy, we stepped on every challenge there could possibly be. Just to name a few:
- In what form do micro-apps publish static resources?
- How does the framework integrate individual micro-apps?
- How to ensure that sub-applications are isolated from one another (development independence and deployment independence) and runtime sandboxed?
- Performance issues? What about public dependencies?
- The list goes on long ...
After solving these common problems of micro frontends and lots of polishing and testing, we extracted the minimal viable framework of our solution, and named it `qiankun`, as it can contain and serve anything. Not long after, it became the cornerstone of hundreds of our web applications in production, and we decided to open-source it to save you the suffering.
**TLDR: Qiankun is probably the most complete micro-frontend solution you ever met🧐.**
## ✨ Features
Qiankun inherits the fundamentals of [single-spa](https://github.com/single-spa/single-spa) — **independent deployment**, **lazy loading**, and a **technology-agnostic** host that never dictates a micro app's stack — and adds the pieces a real product needs:
- 📄 **HTML entry** — point qiankun at a URL, not a manifest of assets. The entry is streamed into the live document as it arrives, so a micro app starts rendering before its HTML has finished downloading.
- 🧳 **JS sandbox** — every micro app runs against a Proxy-membrane view of `window` and `document`, so globals, timers, listeners and dynamic DOM stay inside the app and are reclaimed on unmount. On by default.
- 📦 **Native ESM** — `
```
6. If the development environment is OK but the production environment is not, check whether the `index.html` and `entry js` of the micro app are returned normally, for example, `404.html` is returned.
7. If you're using webpack5 and not using module federation, please see [here](https://github.com/umijs/qiankun/issues/1092#issuecomment-1109673224)
8. If you are using webpack5 and using module federation, you need to expose the life cycle function in the index file, and then expose the life cycle function externally in the bootstrap file.
```js
const promise = import('index');
export const bootstrap = () => promise.then((m) => m.bootstrap());
export const mount = () => promise.then((m) => m.mount());
export const unmount = () => promise.then((m) => m.unmount());
```
9. Check whether the main app and micro-app use AMD or CommonJS. Check method: run the main app and the micro-app independently, and enter the following code in the console: `(typeof exports === 'object' && typeof module === 'object') || (typeof define === 'function' && define.amd) || typeof exports === 'object'`，If it returns `true`，that it is caused by this reason, and there are mainly the following two solutions:
- Solution 1: Modify the `libraryTarget` of the micro-app `webpack` to `'window'`.
```diff
const packageName = require('./package.json').name;
module.exports = {
output: {
library: `${packageName}-[name]`,
- libraryTarget: 'umd',
+ libraryTarget: 'window',
jsonpFunction: `webpackJsonp_${packageName}`,
},
};
```
- Solution 2: The micro-app is not bundle with `umd`, directly mount the life cycle function to the `window` in the entry file, refer to[Micro app built without webpack](/guide/tutorial#micro-app-built-without-webpack).
10. If it still not works after the steps above, this is usually due to browser compatibility issues. Try to **set the webpack `output.library` of the broken sub app the same with your main app registration for your app**, such as:
Such as here is the main configuration:
```ts {4}
// main app
registerMicroApps([
{
name: 'brokenSubApp',
entry: '//localhost:7100',
container: '#yourContainer',
activeRule: '/react',
},
]);
```
Set the `output.library` the same with main app registration:
```js {4}
module.exports = {
output: {
// Keep the same with the registration in main app
library: 'brokenSubApp',
libraryTarget: 'umd',
jsonpFunction: `webpackJsonp_${packageName}`,
},
};
```
## `Application died in status NOT_MOUNTED: Target container with #container not existed after xxx mounted!`
This error thrown as the container DOM does not exist after the micro app is loaded. The possible reasons are:
1. The root id of the micro app conflicts with other DOM, and the solution is to modify the search range of the root id.
`vue` micro app:
```js
function render(props = {}) {
const { container } = props;
instance = new Vue({
router,
store,
render: (h) => h(App),
}).$mount(container ? container.querySelector('#app') : '#app');
}
export async function mount(props) {
render(props);
}
```
`react` micro app：
```js
function render(props) {
const { container } = props;
ReactDOM.render(, container ? container.querySelector('#root') : document.querySelector('#root'));
}
export async function mount(props) {
render(props);
}
export async function unmount(props) {
const { container } = props;
ReactDOM.unmountComponentAtNode(container ? container.querySelector('#root') : document.querySelector('#root'));
}
```
2. Some js of micro app use `document.write`, such as AMAP 1.x version, Tencent Map 2.x version.
If it is caused by the map js, see if the upgrade can be resolved, for example, upgrade the AMAP map to version 2.x.
If the upgrade cannot be resolved, it is recommended to put the map on the main app to load. The micro app also introduces this map js (used in run independently), but add the `ignore` attribute to the `
```
In other cases, please do not use `document.write`.
## `Application died in status NOT_MOUNTED: Target container with #container not existed while xxx mounting!`
This error usually occurs when the main app is Vue, and the container is written on a routing page and uses the routing transition effect. Some special transition effect caused the container not to exist in the mounting process of the micro app. The solution is to use other transition effects, or remove the routing transition.
## `Application died in status NOT_MOUNTED: Target container with #container not existed while xxx loading!`
Similar to the above error, This error thrown as the container DOM does not exist when the micro app is loaded. Generally, it is caused by incorrect calling timing of the `start` function, just adjust the calling timing of the `start` function.
How to determine the completion of the container DOM loading? The vue app can be called during the `mounted` life cycle, and the react app can be called during the `componentDidMount` life cycle.
If it still reports an error, check whether the container DOM is placed on a routing page of the main app, please refer to [How to load micro apps on a routing page of the main app](#How to load micro apps on a routing page of the main app)
## `[import-html-entry]: error occurs while excuting xxx script http://xxx.xxx.xxx/x.js`
The first line is just a helper info printed by qiankun via `console.error` to help users identify which js file threw the error faster. It is not an exception thrown by qiankun itself.
**The actual exception info is in the second line.**
For example in the error above, it means the child app itself threw an exception when executing http://localhost:9100/index.bundle.js. **And the actual exception message is `Uncaught TypeError: Cannot read property 'call' of undefined` in the second line.**
Exceptions from the child app itself can be debugged and fixed with the following steps:
1. Based on the specific exception message, check if the js file that errors has syntax errors, like missing semicolons, depending on uninitialized variables etc.
2. Whether it depends on global variables provided by the main app, but the main app did not initialize them.
3. Compatibility issues. The child app js itself has syntax compatibility issues in the current runtime environment.
## How to load micro apps on a routing page of the main app
It must be ensured that the routing page of the main app is also loaded when the micro app is loaded.
`vue` + `vue-router` main app:
1. When the main app registers this route, add a `*` to `path`, **Note: If this route has other sub-routes, you need to register another route, just use this component**.
```js
const routes = [
{
path: '/portal/*',
name: 'portal',
component: () => import('../views/Portal.vue'),
},
];
```
2. The `activeRule` of the micro app needs to include the route `path` of the main app.
```js
registerMicroApps([
{
name: 'app1',
entry: 'http://localhost:8080',
container: '#container',
activeRule: '/portal/app1',
},
]);
```
3. Call the `start` function in the `mounted` cycle of the `Portal.vue` component, **be careful not to call it repeatedly**.
```js
import { start } from 'qiankun';
export default {
mounted() {
if (!window.qiankunStarted) {
window.qiankunStarted = true;
start();
}
},
};
```
`react` + `react-router` main app：only need to make the activeRule of the sub app include the route of the main app.
`angular` + `angular-router` main app，similar to the Vue app：
1. The main app registers a wildcard sub route for this route, and the content is empty.
```ts
const routes: Routes = [
{
path: 'portal',
component: PortalComponent,
children: [{ path: '**', component: EmptyComponent }],
},
];
```
2. The `activeRule` of the micro app needs to include the route `path` of the main app.
```js
registerMicroApps([
{
name: 'app1',
entry: 'http://localhost:8080',
container: '#container',
activeRule: '/portal/app1',
},
]);
```
3. Call the `start` function in the `ngAfterViewInit` cycle of this routing component, **be careful not to call it repeatedly**.
```ts
import { start } from 'qiankun';
export class PortalComponent implements AfterViewInit {
ngAfterViewInit(): void {
if (!window.qiankunStarted) {
window.qiankunStarted = true;
start();
}
}
}
```
## Vue Router Error - `Uncaught TypeError: Cannot redefine property: $router`
If you pass `{ sandbox: true }` to `start()` function, `qiankun` will use `Proxy` to isolate global `window` object for sub applications. When you access `window.Vue` in sub application's code，it will check whether the `Vue` property in the proxyed `window` object. If the property does not exist, it will look it up in the global `window` object and return it.
There are three lines code in the `vue-router` as followed, and it will access `window.Vue` once the `vue-router` module is loaded. And the `window.Vue` in following code is your master application's `Vue`.
```javascript
if (inBrowser && window.Vue) {
window.Vue.use(VueRouter);
}
```
To solve the error, choose one of the options listed below:
1. Use bundler to pack `Vue` library, instead of CDN or external module
2. Rename `Vue` to other name in master application, eg: `window.Vue2 = window.Vue; delete window.Vue`
## Why dynamic imported assets missing?
The reason is that webpack does not use the correct `publicPath` when loading the resource.
Two way to solve that:
### 1. With webpack live public path config
qiankun will inject a live public path variable before your sub app bootstrap, what you need is to add this code at the top of your sub app entry js:
```js
__webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;
```
For more details, check the [webpack doc](https://webpack.js.org/guides/public-path/#on-the-fly).
Runtime publicPath addresses the problem of incorrect scripts, styles, images, and other addresses for dynamically loaded in sub application.
### 2. With webpack static public path config
You need to set your publicPath configuration to an absolute url, and in development with webpack it might be:
```js
{
output: {
publicPath: `//localhost:${port}`;
}
}
```
### After the micro-app is bundled, the font files and images in the css load 404
The reason is that `qiankun` changed the external link style to the inline style, but the loading path of the font file and background image is a relative path.
Once the `css` file is packaged, you cannot modify the path of the font file and background image by dynamically modifying the `publicPath`.
There are mainly the following solutions:
1. Upload all static resources such as pictures to `cdn`, and directly reference the address of `cdn` in `css` (**recommended**)
2. Use the `url-loader` of `webpack` to package font files and images as `base64` (suitable for projects with small font files and images)(**recommended**)
```js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpe?g|gif|webp|woff2?|eot|ttf|otf)$/i,
use: [
{
loader: 'url-loader',
options: {},
},
],
},
],
},
};
```
`vue-cli3` project:
```js
module.exports = {
chainWebpack: (config) => {
config.module.rule('fonts').use('url-loader').loader('url-loader').options({}).end();
config.module.rule('images').use('url-loader').loader('url-loader').options({}).end();
},
};
```
`vue-cli5` project, use the `asset/inline` of `webpack` replace `url-loader`:
```js
module.exports = {
chainWebpack: (config) => {
config.module.rule('fonts').type('asset/inline').set('generator', {});
config.module.rule('images').type('asset/inline').set('generator', {});
},
};
```
3. Use the `file-loader` of `webpack` to inject the full path when packaging it (suitable for projects with large font files and images)
```js
const publicPath = process.env.NODE_ENV === 'production' ? 'https://qiankun.umijs.org/' : `http://localhost:${port}`;
module.exports = {
module: {
rules: [
{
test: /\.(png|jpe?g|gif|webp)$/i,
use: [
{
loader: 'file-loader',
options: {
name: 'img/[name].[hash:8].[ext]',
publicPath,
},
},
],
},
{
test: /\.(woff2?|eot|ttf|otf)$/i,
use: [
{
loader: 'file-loader',
options: {
name: 'fonts/[name].[hash:8].[ext]',
publicPath,
},
},
],
},
],
},
};
```
`vue-cli3` project:
```js
const publicPath = process.env.NODE_ENV === 'production' ? 'https://qiankun.umijs.org/' : `http://localhost:${port}`;
module.exports = {
chainWebpack: (config) => {
const fontRule = config.module.rule('fonts');
fontRule.uses.clear();
fontRule
.use('file-loader')
.loader('file-loader')
.options({
name: 'fonts/[name].[hash:8].[ext]',
publicPath,
})
.end();
const imgRule = config.module.rule('images');
imgRule.uses.clear();
imgRule
.use('file-loader')
.loader('file-loader')
.options({
name: 'img/[name].[hash:8].[ext]',
publicPath,
})
.end();
},
};
```
4. Combine the two schemes, convert small files to `base64`, and inject path prefixes for large files
```js
const publicPath = process.env.NODE_ENV === 'production' ? 'https://qiankun.umijs.org/' : `http://localhost:${port}`;
module.exports = {
module: {
rules: [
{
test: /\.(png|jpe?g|gif|webp)$/i,
use: [
{
loader: 'url-loader',
options: {},
fallback: {
loader: 'file-loader',
options: {
name: 'img/[name].[hash:8].[ext]',
publicPath,
},
},
},
],
},
{
test: /\.(woff2?|eot|ttf|otf)$/i,
use: [
{
loader: 'url-loader',
options: {},
fallback: {
loader: 'file-loader',
options: {
name: 'fonts/[name].[hash:8].[ext]',
publicPath,
},
},
},
],
},
],
},
};
```
`vue-cli3` project：
```js
const publicPath = process.env.NODE_ENV === 'production' ? 'https://qiankun.umijs.org/' : `http://localhost:${port}`;
module.exports = {
chainWebpack: (config) => {
config.module
.rule('fonts')
.use('url-loader')
.loader('url-loader')
.options({
limit: 4096, // Less than 4kb will be packaged as base64
fallback: {
loader: 'file-loader',
options: {
name: 'fonts/[name].[hash:8].[ext]',
publicPath,
},
},
})
.end();
config.module
.rule('images')
.use('url-loader')
.loader('url-loader')
.options({
limit: 4096, // Less than 4kb will be packaged as base64
fallback: {
loader: 'file-loader',
options: {
name: 'img/[name].[hash:8].[ext]',
publicPath,
},
},
});
},
};
```
5. The `vue-cli3` project can package `css` into `js` without generating files separately (not recommended, only suitable for projects with less `css`)
Configuration reference [vue-cli3 official website](https://cli.vuejs.org/zh/config/#css-extract):
```js
module.exports = {
css: {
extract: false,
},
};
```
## Must a sub app asset support cors?
Yes it is.
Since qiankun get assets which imported by sub app via fetch, these static resources must be required to support [cors](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
If it is your own script, you can support it by developing server-side cross-domain. If it is a 3-legged script and cannot add cross-domain headers to it, you can drag the script to the local and have your own server serve support cross-domain.
See [Enable Nginx Cors](https://enable-cors.org/server_nginx.html).
## How to solve that micro apps loaded failed due to abnormal scripts inserted dynamically by carriers
Scripts inserted by carriers are usually marked with `async` to avoid loading of block micro apps. This is usually no problem, such as:
```html
```
However, if some inserted scripts are not marked as `async`, once such scripts fail to run, the entire application will be blocked and subsequent scripts will no longer be executed. We can solve this problem in the following ways:
### Use a custom `getTemplate` method
Filter abnormal scripts in the HTML template of the micro app through the `getTemplate` method implemented by yourself.
```js
import { start } from 'qiankun';
start({
getTemplate(tpl) {
return tpl.replace('
```
6. 如果开发环境可以，生产环境不行，检查微应用的 `index.html` 和 `entry js` 是否正常返回，比如说返回了 `404.html`。
7. 如果你正在使用 webpack5，但没用使用模块联邦，请看[这个 issues](https://github.com/umijs/qiankun/issues/1092#issuecomment-1109673224)。
8. 如果你正在使用 webpack5，并且使用了使用模块联邦。需要在 index 文件中暴露生命周期函数，然后在 bootstrap 文件向外暴露生命周期函数。
```js
const promise = import('index');
export const bootstrap = () => promise.then((m) => m.bootstrap());
export const mount = () => promise.then((m) => m.mount());
export const unmount = () => promise.then((m) => m.unmount());
```
9. 检查主应用和微应用是否使用了 AMD 或 CommonJS 模块化。检查方法：单独运行微应用和主应用，在控制台输入如下代码：`(typeof exports === 'object' && typeof module === 'object') || (typeof define === 'function' && define.amd) || typeof exports === 'object'`，如果返回 `true`，则说明是这种情况，主要有以下两个解决办法：
- 解决办法 1：修改微应用 `webpack` 的 `libraryTarget` 为 `'window'` 。
```diff
const packageName = require('./package.json').name;
module.exports = {
output: {
library: `${packageName}-[name]`,
- libraryTarget: 'umd',
+ libraryTarget: 'window',
jsonpFunction: `webpackJsonp_${packageName}`,
},
};
```
- 解决办法 2：微应用不打包成 umd ，直接在入口文件把生命周期函数挂载到 window 上，参考[非 webpack 构建的微应用](/zh/guide/tutorial#非-webpack-构建的微应用)。
10. 如果在上述步骤完成后仍有问题，通常说明是浏览器兼容性问题导致的。可以尝试 **将有问题的微应用的 webpack `output.library` 配置成跟主应用中注册的 `name` 字段一致**，如：
假如主应用配置是这样的：
```ts {4}
// 主应用
registerMicroApps([
{
name: 'brokenSubApp',
entry: '//localhost:7100',
container: '#yourContainer',
activeRule: '/react',
},
]);
```
将微应用的 `output.library` 改为跟主应用中注册的一致：
```js {4}
module.exports = {
output: {
// 这里改成跟主应用中注册的一致
library: 'brokenSubApp',
libraryTarget: 'umd',
jsonpFunction: `webpackJsonp_${packageName}`,
},
};
```
## `Application died in status NOT_MOUNTED: Target container with #container not existed after xxx mounted!`
qiankun 抛出这个错误是因为微应用加载后容器 DOM 节点不存在了。可能的原因有：
1. 微应用的根 `id` 与其他 DOM 冲突。解决办法是：修改根 `id` 的查找范围。
`vue` 微应用：
```js
function render(props = {}) {
const { container } = props;
instance = new Vue({
router,
store,
render: (h) => h(App),
}).$mount(container ? container.querySelector('#app') : '#app');
}
export async function mount(props) {
render(props);
}
```
`react` 微应用：
```js
function render(props) {
const { container } = props;
ReactDOM.render(, container ? container.querySelector('#root') : document.querySelector('#root'));
}
export async function mount(props) {
render(props);
}
export async function unmount(props) {
const { container } = props;
ReactDOM.unmountComponentAtNode(container ? container.querySelector('#root') : document.querySelector('#root'));
}
```
2. 微应用的某些 js 里面使用了 `document.write`，比如高德地图 1.x 版本，腾讯地图 2.x 版本。
如果是地图 js 导致的，先看看升级能否解决，比如说高德地图升级到 2.x 版本即可。
如果升级无法解决，建议将地图放到主应用加载，微应用也引入这个地图 js（独立运行时使用），但是给 `
```
如果是其他的情况，请不要使用 `document.write` 。
## `Application died in status NOT_MOUNTED: Target container with #container not existed while xxx mounting!`
这个报错通常出现在主应用为 vue 时，容器写在了路由页面并且使用了路由过渡效果，一些特殊的过渡效果会导致微应用在 mounting 的过程中容器不存在，解决办法就是换成其他的过渡效果，或者去掉路由过渡。
## `Application died in status NOT_MOUNTED: Target container with #container not existed while xxx loading!`
与上面的报错类似，这个报错是因为微应用加载时容器 DOM 不存在。一般是因为 `start` 函数调用时机不正确导致的，调整 `start` 函数调用时机即可。
如何判断容器 DOM 加载完成？vue 应用可以在 `mounted` 生命周期调用，react 应用可以在 `componentDidMount` 生命周期调用。
如果仍然报错，检查容器 DOM 是否放在了主应用的某个路由页面，请参考[如何在主应用的某个路由页面加载微应用](#如何在主应用的某个路由页面加载微应用)。
## `[import-html-entry]: error occurs while excuting xxx script http://xxx.xxx.xxx/x.js`
其中第一行只是 qiankun 通过 `console.error` 打印出来的一个辅助信息，目的是帮助用户更快的知道是哪个 js 报错了，并不是 qiankun 本身发生了异常。
**真正的异常信息在第二行。**
比如上图这样一个报错，指的是子应用在执行 `http://localhost:9100/index.bundle.js` 时，这个 js 本身抛异常了。**而具体的异常信息就是第二行的 `Uncaught TypeError: Cannot read property 'call' of undefined`。**
子应用本身的异常，可以尝试通过以下步骤排查解决：
1. 根据具体的异常信息，检查报错的 js 是否有语法错误，比如少了分号、依赖了未初始化的变量等。
2. 是否依赖了主应用提供的全局变量，但实际主应用并未初始化。
3. 兼容性问题。子应用这个 js 本身在当前运行环境存在语法兼容性问题。
## 如何在主应用的某个路由页面加载微应用
必须保证微应用加载时主应用这个路由页面也加载了。
`vue` + `vue-router` 技术栈的主应用：
1. 主应用注册这个路由时给 `path` 加一个 `*`，**注意：如果这个路由有其他子路由，需要另外注册一个路由，仍然使用这个组件即可**。
```js
const routes = [
{
path: '/portal/*',
name: 'portal',
component: () => import('../views/Portal.vue'),
},
];
```
2. 微应用的 `activeRule` 需要包含主应用的这个路由 `path`。
```js
registerMicroApps([
{
name: 'app1',
entry: 'http://localhost:8080',
container: '#container',
activeRule: '/portal/app1',
},
]);
```
3. 在 `Portal.vue` 这个组件的 `mounted` 周期调用 `start` 函数，**注意不要重复调用**。
```js
import { start } from 'qiankun';
export default {
mounted() {
if (!window.qiankunStarted) {
window.qiankunStarted = true;
start();
}
},
};
```
`react` + `react-router` 技术栈的主应用：只需要让微应用的 `activeRule` 包含主应用的这个路由即可。
`angular` + `angular-router` 技术栈的主应用，与 vue 项目类似：
1. 主应用给这个路由注册一个通配符的子路由，内容为空。
```ts
const routes: Routes = [
{
path: 'portal',
component: PortalComponent,
children: [{ path: '**', component: EmptyComponent }],
},
];
```
2. 微应用的 `activeRule` 需要包含主应用的这个路由 `path`。
```js
registerMicroApps([
{
name: 'app1',
entry: 'http://localhost:8080',
container: '#container',
activeRule: '/portal/app1',
},
]);
```
3. 在这个路由组件的 `ngAfterViewInit` 周期调用 `start` 函数，**注意不要重复调用**。
```ts
import { start } from 'qiankun';
export class PortalComponent implements AfterViewInit {
ngAfterViewInit(): void {
if (!window.qiankunStarted) {
window.qiankunStarted = true;
start();
}
}
}
```
## Vue Router 报错 `Uncaught TypeError: Cannot redefine property: $router`
qiankun 中的代码使用 Proxy 去代理父页面的 window，来实现的沙箱，在微应用中访问 `window.Vue` 时，会先在自己的 window 里查找有没有 `Vue` 属性，如果没有就去父应用里查找。
在 VueRouter 的代码里有这样三行代码，会在模块加载的时候就访问 `window.Vue` 这个变量，微应用中报这个错，一般是由于父应用中的 Vue 挂载到了父应用的 `window` 对象上了。
```javascript
if (inBrowser && window.Vue) {
window.Vue.use(VueRouter);
}
```
可以从以下方式中选择一种来解决问题：
1. 在主应用中不使用 CDN 等 external 的方式来加载 `Vue` 框架，使用前端打包软件来加载模块
2. 在主应用中，将 `window.Vue` 变量改个名称，例如 `window.Vue2 = window.Vue; delete window.Vue`
## 为什么微应用加载的资源会 404？
原因是 webpack 加载资源时未使用正确的 `publicPath`。
可以通过以下两个方式解决这个问题：
### a. 使用 webpack 运行时 publicPath 配置
qiankun 将会在微应用 bootstrap 之前注入一个运行时的 publicPath 变量，你需要做的是在微应用的 entry js 的顶部添加如下代码：
```js
__webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;
```
关于运行时 publicPath 的技术细节，可以参考 [webpack 文档](https://webpack.js.org/guides/public-path/#on-the-fly)。
runtime publicPath 主要解决的是微应用动态载入的 脚本、样式、图片 等地址不正确的问题。
### b. 使用 webpack 静态 publicPath 配置
你需要将你的 webpack `publicPath` 配置设置成一个绝对地址的 url，比如在开发环境可能是：
```js
{
output: {
publicPath: `//localhost:${port}`,
}
}
```
### 微应用打包之后 css 中的字体文件和图片加载 404
原因是 `qiankun` 将外链样式改成了内联样式，但是字体文件和背景图片的加载路径是相对路径。
而 `css` 文件一旦打包完成，就无法通过动态修改 `publicPath` 来修正其中的字体文件和背景图片的路径。
主要有以下几个解决方案：
1. 所有图片等静态资源上传至 `cdn`，`css` 中直接引用 `cdn` 地址（**推荐**）
2. 借助 `webpack` 的 `url-loader` 将字体文件和图片打包成 `base64`（适用于字体文件和图片体积小的项目）（**推荐**）
```js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpe?g|gif|webp|woff2?|eot|ttf|otf)$/i,
use: [
{
loader: 'url-loader',
options: {},
},
],
},
],
},
};
```
`vue-cli3` 项目写法：
```js
module.exports = {
chainWebpack: (config) => {
config.module.rule('fonts').use('url-loader').loader('url-loader').options({}).end();
config.module.rule('images').use('url-loader').loader('url-loader').options({}).end();
},
};
```
`vue-cli5` 项目，使用 `asset/inline` 替代 `url-loader`，写法：
```js
module.exports = {
chainWebpack: (config) => {
config.module.rule('fonts').type('asset/inline').set('generator', {});
config.module.rule('images').type('asset/inline').set('generator', {});
},
};
```
3. 借助 `webpack` 的 `file-loader` ，在打包时给其注入完整路径（适用于字体文件和图片体积比较大的项目）
```js
const publicPath = process.env.NODE_ENV === 'production' ? 'https://qiankun.umijs.org/' : `http://localhost:${port}`;
module.exports = {
module: {
rules: [
{
test: /\.(png|jpe?g|gif|webp)$/i,
use: [
{
loader: 'file-loader',
options: {
name: 'img/[name].[hash:8].[ext]',
publicPath,
},
},
],
},
{
test: /\.(woff2?|eot|ttf|otf)$/i,
use: [
{
loader: 'file-loader',
options: {
name: 'fonts/[name].[hash:8].[ext]',
publicPath,
},
},
],
},
],
},
};
```
`vue-cli3` 项目写法：
```js
const publicPath = process.env.NODE_ENV === 'production' ? 'https://qiankun.umijs.org/' : `http://localhost:${port}`;
module.exports = {
chainWebpack: (config) => {
const fontRule = config.module.rule('fonts');
fontRule.uses.clear();
fontRule
.use('file-loader')
.loader('file-loader')
.options({
name: 'fonts/[name].[hash:8].[ext]',
publicPath,
})
.end();
const imgRule = config.module.rule('images');
imgRule.uses.clear();
imgRule
.use('file-loader')
.loader('file-loader')
.options({
name: 'img/[name].[hash:8].[ext]',
publicPath,
})
.end();
},
};
```
4. 将两种方案结合起来，小文件转 `base64` ，大文件注入路径前缀
```js
const publicPath = process.env.NODE_ENV === 'production' ? 'https://qiankun.umijs.org/' : `http://localhost:${port}`;
module.exports = {
module: {
rules: [
{
test: /\.(png|jpe?g|gif|webp)$/i,
use: [
{
loader: 'url-loader',
options: {},
fallback: {
loader: 'file-loader',
options: {
name: 'img/[name].[hash:8].[ext]',
publicPath,
},
},
},
],
},
{
test: /\.(woff2?|eot|ttf|otf)$/i,
use: [
{
loader: 'url-loader',
options: {},
fallback: {
loader: 'file-loader',
options: {
name: 'fonts/[name].[hash:8].[ext]',
publicPath,
},
},
},
],
},
],
},
};
```
`vue-cli3` 项目写法：
```js
const publicPath = process.env.NODE_ENV === 'production' ? 'https://qiankun.umijs.org/' : `http://localhost:${port}`;
module.exports = {
chainWebpack: (config) => {
config.module
.rule('fonts')
.use('url-loader')
.loader('url-loader')
.options({
limit: 4096, // 小于4kb将会被打包成 base64
fallback: {
loader: 'file-loader',
options: {
name: 'fonts/[name].[hash:8].[ext]',
publicPath,
},
},
})
.end();
config.module
.rule('images')
.use('url-loader')
.loader('url-loader')
.options({
limit: 4096, // 小于4kb将会被打包成 base64
fallback: {
loader: 'file-loader',
options: {
name: 'img/[name].[hash:8].[ext]',
publicPath,
},
},
});
},
};
```
5. `vue-cli3` 项目可以将 `css` 打包到 `js`里面，不单独生成文件(不推荐，仅适用于 `css` 较少的项目)
配置参考 [vue-cli3 官网](https://cli.vuejs.org/zh/config/#css-extract):
```js
module.exports = {
css: {
extract: false,
},
};
```
## 微应用静态资源一定要支持跨域吗？
是的。
由于 qiankun 是通过 fetch 去获取微应用的引入的静态资源的，所以必须要求这些静态资源支持[跨域](https://developer.mozilla.org/zh/docs/Web/HTTP/Access_control_CORS)。
如果是自己的脚本，可以通过开发服务端跨域来支持。如果是三方脚本且无法为其添加跨域头，可以将脚本拖到本地，由自己的服务器 serve 来支持跨域。
参考：[Nginx 跨域配置](https://segmentfault.com/a/1190000012550346)
## 如何解决由于运营商动态插入的脚本加载异常导致微应用加载失败的问题
运营商插入的脚本通常会用 async 标记从而避免 block 微应用的加载，这种通常没问题，如：
```html
```
但如果有些插入的脚本不是被标记成 async 的，这类脚本一旦运行失败，将会导致整个应用被 block 且后续的脚本也不再执行。我们可以通过以下几个方式来解决这个问题：
### 使用自定义的 getTemplate 方法
通过自己实现的 getTemplate 方法过滤微应用 HTML 模板中的异常脚本
```js
import { start } from 'qiankun';
start({
getTemplate(tpl) {
return tpl.replace('