# @epam/microfrontends 中文文档

规范地址：https://npmcn.com/package/%40epam/microfrontends/

版本：1\.2\.2
npm 元数据更新时间：2026-06-05T11:44:53.798Z
中文译文更新时间：2026-11-13T19:26:49.660Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40epam/microfrontends
原文对照：https://npmcn.com/package/%40epam/microfrontends/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：388 kB，85 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：react \>=16
- 首次发布：2023-08-08T09:44:48.417Z
- 最新版本发布：2026-06-05T11:44:53.575Z
- 近 30 天下载量：3887（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 5 个）

## 中文简介

提供一组帮助和CLI工具来方便微前端部件的开发.

## 安装

```sh
npm install @epam/microfrontends
```

也可以使用：`pnpm add @epam/microfrontends`、`yarn add @epam/microfrontends`、`bun add @epam/microfrontends`

## README

# @ epam/ 微前端

这个软件包包含了简化微前端开发的公用设施和脚本.

### 定义

-   远程应用程序:主机远程部件的应用程序.
-   主机应用程序:生成远程部件的应用程序.
-   远程外观( N)`widgets.js`:在"Remote app"上托管的统一界面被"Host app"用于渲染远程部件.

### 主思想

"Host app"使用"Remote外观"从"Remote app"中取回了远程部件,该软件位于一个著名的URL.

举例来说,这是比较好的.  
让我们假设 `Remote app` 此来源为: `http://127.0.0.1:4000`  
主办方认为 `Remote facade` 它位于一个著名的 URL,它看起来像: `http://127.0.0.1:4000/widgets.js`  
由"Remote app"托管的有其他几种资源,而"Host"不知道此类资源的存在. 然而,它们被隐含地使用(由 `widgets.js`在远程部件的安装中。 以下是资源清单:

-   远程资产表`http://127.0.0.1:4000/<path_to_build_manifest>`(中文(简体) )
-   远程 App JS 捆绑`http://127.0.0.1:4000/<path_to_main_js_bundle>`(中文(简体) )
-   远程 App CSS 捆绑 (`http://127.0.0.1:4000/<path_to_main_css_bundle>`(中文(简体) )

以下是主机为挂载远程部件而执行的动作序列 .

1.  洛杉矶
    
    ```javascript
    // The "Remote facade" is loaded using a well-known URL. Internally, the Host loads the widget like this.
    const remote = await import('http://127.0.0.1:4000/widgets.js');
    ```
    
2.  内 容
    
    ```javascript
    /**
    * Several IMPLICIT actions are done during the init(). The Host doesn't know anything about these actions; they are encapsulated inside "widgets.js".
    * 1) The "Remote Assets Manifest" file is loaded (if applicable).
    * 2) The URL to the "Remote App JS bundle" is determined from the manifest (if applicable).
    * 3) The URL to the "Remote App CSS bundle" is determined from the manifest (if applicable).
    * 4) The window.Widgets global variable is created (unless already defined). It acts as a simple registry that helps to define/require widgets.
    * 5) The "Remote App JS bundle" is loaded via window.Widgets.require(/../). Note: A "script" tag is used under the hood to load the JS bundle. It's loaded only once and cached.
    * 6) Widgets defined during the load (via window.Widgets.define(...)) are collected.
    * Note: The "Remote App CSS bundle" is NOT loaded at this step. It will be loaded later, during the widget "mount".
    */
    const widgets = await remote.default.init(context /* this context is optional */);
    ```
    
3.  备忘录
    
    ```javascript
    // The "Remote App CSS bundle" is loaded as part of this call (right before the actual mount occurs).
    const { unmount } = widgets['demoWidget'].mount(/*...*/);
    ```
    
4.  弹药
    
    ```javascript
    // The "Remote App CSS bundle" is unloaded after this step.
    unmount();
    ```
    

## 已知问题

见 [识相相相克. md](https://npmcn.com/package/%40epam/microfrontends/KNOWN_ISSUES.md)

### "相去相去"(widgets.js)的地物

-   自定义挂载的可能性(详情见CLI 使用等)
-   规定 a `Widgets` 支持以流行格式装入捆绑的模块系统(IIFE、无害环境管理)
-   已处理 `Babel` 以保证与浏览器兼容
-   处理错误
-   转角案件处理
-   概括分析不同类型资产表文件的逻辑
-   它只主机在远程侧,因为它包含远程应用程序特有的逻辑

### CLI 使用量

#### (Remote app) 生成远程外观 (widgets.js)

从下面运行命令 `remote` 项目的根文件夹 . 它创建“ 外观” 文件并将其放入 `./public` 文件夹.  
_注:_ 它需要运行 第一次, 只能再次运行 `@epam/microfrontends` 软件包版本已更改.

```shell
# 1) Without installing the NPM package, this is preferable. Exact version can be specified instead of "latest".
npx --yes @epam/microfrontends@latest epam-microfrontends-init --app-type=webpack
# 2) When "@epam/microfrontends" is installed locally.
npx epam-microfrontends-init --app-type=webpack
```

将创建以下文件:

-   `widgets.js (+ widgets.js.map)` - 远程版的"Remote facecade"的精密版本. "Host app"下载并运行此文件以获取远程部件.
-   `widgets.dev.js and widgets-dev.html` - 不可忽略的"背面"版本. 它可能被用作在当地孤立地测试远程部件的起点.  
    注:删除这些文件是安全的,除非您计划通过“widgets-dev.html”本地测试您的部件.

所有选项 :

\--app-type (required)  Application type (in all cases the widget.js/widgets-dev.html will be copied to "./public" dir)  
        webpack - for Webpack apps
        vite - for Vite apps
        angular - for Angular apps
--bundle-format (optional)  The format of the app bundle which contains single Widgets.define(...):
        iife - when bundle is IIFE (this is a default value for --app-type=webpack
        esm - when bundle is ESM (this is a default value for --app-type=vite and --app-type=angular)
--remote-css (optional)
        shadowRoot (this is a default value for --app-type=webpack and --app-type=vite) - the CSS will be added to the shadow root of the target element 
        global - the CSS will be added to the document.head of the host page.
        skip - (this is a default value for --app-type=angular) CSS will be loaded as part of mount method of the remote widget.
--add-css-to-host (optional)
        {path} - path to the css on remote widget's server. It will be injected into the host page when the widget mounts. E.g.: /app/app\_name/host/styles.css
--reset-css-in-shadow-dom (optional)
        {boolean} - when true (it is by default), it adds inline style which resets CSS in ShadowRoot

#### (Angular app- specific) 生成资产管理. json

```shell
# Run next CLI command AFTER every Angular build. This command will generate asset-manifest based on the Angular build output (directory "./dist")
npx --yes @epam/microfrontends@latest epam-microfrontends-init --cmd=angular
```

### 反应

#### 定义远程部件

```typescript
import { createRoot } from 'react-dom/client';
import { IHistoryMicroFe } from '@epam/microfrontends/helpers/history';
const demoWidget = {
    mount: (target: HTMLElement, params: any) => {
        /*
         * If a remote widget uses routing, then it's necessary to do all routing via the "params.historyMicroFe".
         * Use "params.historyMicroFe" directly or via converters exported from "@epam/microfrontends/helpers/history"
         */
        const root = createRoot(target);
        root.render(<DemoWidgetComponent />);
        return {
            unmount: () => {
                root.unmount();
            }
        }
    }
};
if (isPartOfTheNormalApp) {
    // render app
}
(window as any).Widgets?.define(() => ({
    demoWidget,
}));
```

#### 控制远程部件

```typescript
import { RemoteWidget, RemoteWidgetContext } from '@epam/microfrontends/helpers/react';
import { IHistory4Full_to_IHistoryMicroFe } from '@epam/microfrontends/helpers/history';
import { createBrowserHistory } from 'history';
//...//
const history = createBrowserHistory();
const historyMicroFe = IHistory4Full_to_IHistoryMicroFe(history as any);
//...//
function App() {
    // Somewhere in the app:
    const params = { historyMicroFe };
    return (
        <RemoteWidgetContext.Provider value={params}>
            <RemoteWidget
                url="http://172.20.0.1:4001/widgets.js"
                name="demoWidget"
            />
            <RemoteWidget
                url="http://172.20.0.1:4002/widgets.js"
                name="demoWidget"
            />
        </>
    )
}
```

### 角质

#### (远程) 定义远程部件

```typescript
// 1. Add widget component
@Component({
    selector: `demoWidget-root`,
    standalone: true,
    templateUrl: "./demoWidget.component.html",
    encapsulation: ViewEncapsulation.ShadowDom,
})
export class DemoWidgetComponent {
    title = "angular";
}

// 2. Register remote widget
(window as any).Widgets?.define(() => ({
    demoWidget: {
        mount: (targetElement: HTMLElement, props: Record<string, any>) => {
            targetElement.appendChild(document.createElement(`demoWidget-root`));
            bootstrapApplication(AppComponent, {
                providers: [{ provide: YOUR_TOKEN, useValue: props.yourValue }] }
            ).catch((err) => console.error(err));
            return { unmount: () => {} };
        }
    },
}));
```

#### 控制远程部件

```typescript
import { RemoteWidgetComponent } from '@epam/microfrontends/helpers/angular17';
//...//
@Component({
    selector: 'mfe-demo',
    standalone: true,
    imports: [RemoteWidgetComponent],
    template: '<mfe-angular [url]="url" [widgetName]="widgetName" [props]="props"></mfe-angular>',
})
export class AppComponent {
    public url = `http://localhost:4004/apps/remotes-angular/widgets.js`;
    public widgetName = 'demoWidget';
    public props = { yourValue: { id: '1', name: 'Input for mfe Angular' } };
}
```

### 在远程部件中运行

严格地说,这个库对如何在远程或主机中执行路由没有任何限制. 本节仅载有在大多数典型情况下可能有用的建议.

如果一些远程部件使用路由,那么预计它应该使用由"Host app"提供的"HoryMicroFe"标准接口. 一般情况下,主机和远程可以使用不同的路由器,例如:  
(HOST: 未知1) -- -- >(IHistoryMicroFe) -- >(REMOTE: 未知2)

在这种情况下,需要一些适配器:

1.  未知 1 - > 历史缩写
2.  IHistoryMicroFe - > 未知数 2

此软件包中有多个适配器可用 OOTB. 它们涵盖一些典型的使用案例:

-   IHistory4Full to IHistoryMicroFe (英语)
-   Irouter6 to IHistoryMicroFe (英语)
-   IHistoryMicroFe to IHistory 路透社6
-   IHistoryMicroFe to IHistory4Full (英语)

#### 使用“ 基准名 ”

-   预计"Host app"不会使用路由器的"basename"特性. 因此,该全位置路径被"Remote app"所曝光.
-   如有需要,"Remote app"可以选择使用"basename"进行路由. 见这里的例子: `packages/examples/remotes/cra-router5/src/widgets/demoWidget/demoWidget.tsx`

## 常见问题

### @epam/microfrontends 是什么？

提供一组帮助和CLI工具来方便微前端部件的开发\.

### 如何安装 @epam/microfrontends？

在项目目录运行 npm install @epam/microfrontends，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 epam-microfrontends-init，可以用 npx epam-microfrontends-init 直接运行。

### @epam/microfrontends 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @epam/microfrontends 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @epam/microfrontends 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @epam/microfrontends 可以商用吗？

@epam/microfrontends 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @epam/microfrontends 的下载量有多少？

根据 npm 官方下载统计，@epam/microfrontends 在 2026/10/14 – 2026/11/12 这 30 天内被下载 3,887 次，日均约 130 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @epam/microfrontends 还在维护吗？

最新版本 1\.2\.2 发布于 2026/06/05（5 个月前）；至今共发布 23 个版本，其中过去 12 个月发布了 5 个；首次发布于 2023/08/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。