# @appshell/webpack-plugin 中文文档

规范地址：https://npmcn.com/package/%40appshell/webpack-plugin/

版本：1\.0\.0-alpha\.148
npm 元数据更新时间：2026-10-29T16:06:33.902Z
中文译文更新时间：2026-11-06T12:31:38.411Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40appshell/webpack-plugin
原文对照：https://npmcn.com/package/%40appshell/webpack-plugin/?lang=original
项目主页：https://github.com/appshellhq/appshell#readme
源码仓库：https://github.com/appshellhq/appshell

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

- 包体积（解压后）：913 kB，47 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：webpack ^5\.106\.0，@module-federation/enhanced ^2\.8\.2
- 首次发布：2026-08-18T05:20:15.889Z
- 最新版本发布：2026-10-29T16:06:33.095Z
- 近 30 天下载量：6093（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：140（近 12 个月 140 个）

## 中文简介

Webpack 插件用于为模块联盟所建的微前端生成全局 Appshell 配置

## 安装

```sh
npm install @appshell/webpack-plugin
```

也可以使用：`pnpm add @appshell/webpack-plugin`、`yarn add @appshell/webpack-plugin`、`bun add @appshell/webpack-plugin`

## README

[![appshell](https://github.com/navaris/appshell/blob/main/assets/branding/appshell-logo_2x.png)](https://github.com/navaris/appshell)

[![Appshell CI](https://github.com/navaris/appshell/actions/workflows/pipeline.yml/badge.svg)](https://github.com/navaris/appshell/actions/workflows/pipeline.yml)

# @appshell/webpack-plugin (英语)

以 Appshell 和 Webpack Module Federation 创建微前端的 appshell 显示模板 。 appshell 显示模板被子处理以生成一个 `appshell manifest`。 。 。 .

工作实例可见于此 [这里](https://github.com/navaris/appshell/tree/main/examples)。 。 。 .

## 开始

开始,你需要安装 `@appshell/webpack-plugin`数字 :

```console
npm install @appshell/webpack-plugin --save-dev
```

或者说

```console
yarn add -D @appshell/webpack-plugin
```

或者说

```console
pnpm add -D @appshell/webpack-plugin
```

然后将插件添加到 `webpack` 每个远程包的配置 。 例如:

**网络包装. config.js**

```js
const { AppshellPlugin } = require('@appshell/webpack-plugin');

module.exports = {
  plugins: [
    new AppshellPlugin({
      config: './path/to/appshell.config.yaml',
    }),
  ],
};
```

## 远程配置 : `appshellRemote()`

大部分远程的网页包装配置不是作者的选择:注册和 `@appshell/react-shell` 它需要每一个遥控器. `appshellRemote()` 返回该部分,然后您 用你自己的装载器扩展,通常使用 `webpack-merge`它需要 `@module-federation/enhanced` 安装在它旁边.

```js
const { merge } = require('webpack-merge');
const { appshellRemote } = require('@appshell/webpack-plugin');
const { dependencies } = require('./package.json');

module.exports = (_env, { mode }) =>
  merge(
    appshellRemote({
      name: 'PackagesModule',
      exposes: { './Packages': './src/Packages' },
      port: 7302,
      mode,
      react: true,
      dependencies,
    }),
    {
      resolve: { extensions: ['.js', '.ts', '.tsx'] },
      module: {
        rules: [
          /* your transpiler, your CSS */
        ],
      },
    },
  );
```

其设定和要求:

| 设置 | 要求为: |
| --- | --- |
| 没有源地图 `eval` 促进发展 | 登记册在CSP下为壳页服务,禁止 `eval`,所以开发的默认源地图在远程运行前抛出. |
| `publicPath: 'auto'` | 登记册为远程文件服务 `/p/<scope>/<name>/<version>/` 在应用程序本身的源头上,一个覆盖从dev服务器上为它们服务:路径只有在输入负载时才知道. |
| 内容屏蔽块, 未屏蔽块 `remoteEntry.js` | 块的名称是它的字节,所以没有字节对一新条目和一旧块。 该条目是已公布的列表名称的文档. |
| 一个带有 CORS 的 Dev 服务器, `allowedHosts`重装套接字 `localhost` | 重叠:页上是应用程序的出处和代码 `localhost`。服务器绑定每个接口,否则会烘焙 `0.0.0.0`,浏览器无法拨打,进入客户端. |
| `ModuleFederationPlugin` 与 `appshellShared` | `@appshell/react-shell` 是联合会的东道主和共享 appshell 的运行时间,并与 `react`,反应及其约束,作为单子. |
| `AppshellPlugin` | 写一个出版物发送的列表. |

**默认可以覆盖 :**

-   Dev服务器只覆盖了构建错误的页面:警告留在终端,被页面上其他东西所抛出的错误,如浏览器扩展,不是远程的.
-   `allowedHosts` 实值 `'all'`,因为 dev 服务器已经用 CORS 来回答每个源 。 指定应用程序的主机以缩小范围, 例如 `['.appshell.org']`。 。 。 .
-   一个警告 `@appshell/react`'从它的联邦运行时间的动态导入中'捆绑的事业被忽略了.

**未列入**因为他们是你的: 一个转接器,CSS和测试。 一个集装箱自己 合同也不包括在内。 工作空间 `react-router` 例如,添加了单通 结束 `shared` 以远方的大地发誓

```js
appshellRemote({ …, shared: { 'react-router': { singleton: true, requiredVersion: dependencies['react-router'] } } });
```

| 选项 | 默认 | 含义 |
| --- | --- | --- |
| `name` |  | 联邦集装箱的名称,范围 其显示名称. |
| `exposes` |  | 它所暴露的,作为 `ModuleFederationPlugin` 拿着. |
| `port` |  | Dev服务器的端口,要用一个覆盖来指向. |
| `mode` |  | webpack 模式,随着它的 CLI 传递到一个配置函数. |
| `react` | `false` | 共享回放和appshell的回放捆绑. |
| `dependencies` | `{}` | 通常情况下 `package.json`是因为 `dependencies`,将共享范围标出. |
| `shared` | `{}` | 共享超过appshell的预设,合并最后. |
| `entry` | 第一个曝光模块 | 建筑入道. |
| `uniqueName` | `name` | `output.uniqueName`将两个遥控器分开. |
| `allowedHosts` | `'all'` | 主机允许打开 Dev 服务器的重装套接字 . |
| `plugin` |  | 备选方案 `AppshellPlugin`。 。 。 . |

## 继续出版

插件可以在每次成功构建后向 Appshell 注册机构发布生成的表, 如此跑动 `--watch` 工作时保留应用程序. **开发大楼 默认** ——你从不切换每个项目——而生产建设从不自行出版.

```js
new AppshellPlugin({
  config: './path/to/appshell.config.yaml',
  // registry / application are usually omitted — see below.
  registry: 'https://registry.example.com', // optional override
  application: 'acme/my-dev', // optional: activate the published version here
});
```

默认情况下, 插件会遵从您的 **CLI 语境** ——您设置的注册、申请和令牌 与 `appshell config set` 财务报告和审定财务报表 `appshell login` (存储于 `~/.appshell`) (中文(简体) ). 就是这个背景 cLI 使用,所以一个机器级的设置驱动两种;一个项目不需要每个repo配置.

分辨率优先级, 每个字段: 明确的插件选项 `APPSHELL_*` (原始内容存档于2018-10-21) (中文(简体) ). env var `~/.appshell` 上下文 – 默认。 当一个选项或env var指 某处,不是你坚持的上下文 插件警告它压倒它 .

| 外地 | 选项 | 新闻 var | 页:1 |
| --- | --- | --- | --- |
| 发布 | `publish` | `APPSHELL_PUBLISH_ON_BUILD` | 默认为 `true` 处于开发模式; 设置 `0`编号 :`false` 选择退出 |
| 登记 | `registry` | `APPSHELL_REGISTRY` | 默认从 CLI 上下文 |
| 应用程序 | `application` | `APPSHELL_APPLICATION` | `scope/name` (或与 `APPSHELL_SCOPE_ID`; 省略不激活而发布 |
| 部队 | `force` | —— 说 | 覆盖已更改的版本; 默认为 `true` dev 模式 |
| 符号 | —— 说 | `APPSHELL_TOKEN` | 否则从 `~/.appshell/credentials`; 绝不是一个插件选项 |

在CI中没有 `~/.appshell`这样 `APPSHELL_REGISTRY`, (中文(简体) ), `APPSHELL_APPLICATION`,以及 `APPSHELL_TOKEN` 是整个故事。 如果在开发中默认发布但无法解决注册,则构建 仍然成功 —— 以警告跳过出版 .

软件包在其 **无** 名称和版本,无范围——登记处负责范围 从你的标志。 两次发布相同的内容都是不开放的,所以一个重建的手表循环没有 一个版本的凸起是无害的。 出版 _不同_ 现有版本下的内容通常 已拒绝; 在开发模式中, 插件请注册处覆盖它, 它是本地的( 未认证) 默认的注册荣誉,除非配置为 `ALLOW_FORCE_PUBLISH`。 。 。 .

失败的发布被报告为编译错误而不是抛出, 所以 `--watch` 报告并 继续跑.

**什么是 appshell.config.yaml ?**

> 由插件所消耗的配置文件,为Appshell主机提供远程切入点,路由,显示名称等额外信息和上下文.

样本 appshell.config.yaml

```yaml
remotes:
  TestModule/Foo: # Must match the scope/module defined in ModuleFederationPlugin
    url: ${APPS_TEST_URL}/remoteEntry.js # Application variables will be expanded when the global runtime manifest is generated.
    metadata: # Use metadata to provide additional information
      route: ${FOO_ROUTE}
      displayName: Foo App
      displayGroup: primary
      order: 10
      icon: ViewList

  TestModule/Bar:
    url: ${APPS_TEST_URL}/remoteEntry.js
    metadata:
      route: /bar
      displayName: Bar App
      displayGroup: primary
      order: 20
      icon: ViewList

  BizModule/Biz:
    url: http://localhost:4040/remoteEntry.js
    metadata:
      route: /biz
      displayName: Biz App
      displayGroup: utility
      order: 30
      icon: ViewList

vars:
  RUNTIME_ARG_1: ${RUNTIME_ARG_1}
  RUNTIME_ARG_2: ${RUNTIME_ARG_2}
  RUNTIME_ARG_3: ${RUNTIME_ARG_3}
```

> **说明** 变量扩展语法 `${CRA_MFE_URL}`当 `appshell manifest` 生成实际运行时间环境值.

> **说明** 页:1 `vars` 定义运行时配置值 `getVars()` 从 [`@appshell/runtime/vars`](https://npmcn.com/package/%40appshell/runtime/README.md) 一旦装入。 软件包必须共享 `@appshell/runtime` 作为接收他们的单子 见一用例.

**建筑时间会怎样?**

> 插件释放出一个显示模板文件,用于生成 `appshell manifest` 在运行时间.

## 样本产出

```json
{
  "remotes": {
    "CraModule/App": {
      "url": "${CRA_MFE_URL}",
      "metadata": {
        "route": "/cra",
        "displayName": "Example App",
        "displayGroup": "${CRA_MFE_DISPLAY_GROUP}",
        "order": 10,
        "icon": "ViewList"
      },
      "id": "3eb81a0c"
    }
  },
  "module": {
    "exposes": {
      "./App": "./src/App"
    },
    "filename": "remoteEntry.js",
    "name": "CraModule",
    "shared": {
      "react": {
        "singleton": true,
        "requiredVersion": "^18.2.0"
      },
      "react-dom": {
        "singleton": true,
        "requiredVersion": "^18.2.0"
      }
    }
  }
}
```

**我该如何生成应用软件清单?**

> 使用 [@ appshell/ cli (英语)](https://www.npmjs.com/package/@appshell/config) 在启动脚本中 :

```bash
appshell generate manifest --template appshell.template.json
```

样本 `appshell manifest`数字 :

```json
{
  "remotes": {
    "CraModule/App": {
      "id": "3eb81a0c",
      "url": "http://localhost:3000/remoteEntry.js",
      "scope": "CraModule",
      "module": "./App",
      "metadata": {
        "route": "/cra",
        "displayName": "Example App",
        "displayGroup": "primary",
        "order": 10,
        "icon": "ViewList"
      }
    },
    "VanillaModule/Vanilla": {
      "id": "8232ce86",
      "url": "http://localhost:5000/remoteEntry.js",
      "scope": "VanillaModule",
      "module": "./Vanilla",
      "metadata": {
        "route": "/vanilla",
        "displayName": "Example React App",
        "displayGroup": "primary",
        "order": 10,
        "icon": "ViewList"
      }
    }
  },
  "modules": {
    "Appshell": {
      "name": "Appshell",
      "shared": {
        "react": {
          "singleton": true,
          "requiredVersion": "^18.2.0"
        },
        "react-dom": {
          "singleton": true,
          "requiredVersion": "^18.2.0"
        }
      }
    },
    "CraModule": {
      "exposes": {
        "./App": "./src/App"
      },
      "filename": "remoteEntry.js",
      "name": "CraModule",
      "shared": {
        "react": {
          "singleton": true,
          "requiredVersion": "^18.2.0"
        },
        "react-dom": {
          "singleton": true,
          "requiredVersion": "^18.2.0"
        }
      }
    },
    "VanillaModule": {
      "exposes": {
        "./Vanilla": "./src/App"
      },
      "filename": "remoteEntry.js",
      "name": "VanillaModule",
      "shared": {
        "react": {
          "singleton": true,
          "requiredVersion": "^18.2.0"
        },
        "react-dom": {
          "singleton": true,
          "requiredVersion": "^18.2.0"
        }
      }
    }
  },
  "vars": {
    "CraModule": {
      "RUNTIME_ARG_1": "Foo",
      "RUNTIME_ARG_2": "Biz"
    },
    "VanillaModule": {
      "RUNTIME_ARG_1": "Bar"
    }
  }
}
```

## 选项

-   **[`options`](https://npmcn.com/package/%40appshell/webpack-plugin/#readme-options-1)**

插件的签名 :

**网络包装. config.js**

```js
const { AppshellPlugin } = require('@appshell/webpack-plugin');

module.exports = {
  plugins: [
    new AppshellPlugin({
      config: './path/to/appshell.config.yaml',
    }),
  ],
};
```

### `Options`

| 选项 | 类型 | 默认 | 目的 |
| --- | --- | --- | --- |
| `config` | `string` | `appshell.config.yaml` | 配置文件的位置 |
| `registry` | `string` | CLI 语境 | 书记官处将出版到 |
| `application` | `string` | CLI 语境 | 用于激活已发布版本的应用程序 |
| `publish` | `boolean` | `true` 促进发展 | 每次成功构建后发布 |
| `force` | `boolean` | `true` 促进发展 | 请注册处覆盖内容不同的现有版本 |

`registry` 财务报告和审定财务报表 `application` 通常省略——见 [继续出版](https://npmcn.com/package/%40appshell/webpack-plugin/#readme-publishing-on-build) 为决议令.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40appshell/webpack-plugin/LICENSE)

## 常见问题

### @appshell/webpack-plugin 是什么？

Webpack 插件用于为模块联盟所建的微前端生成全局 Appshell 配置

### 如何安装 @appshell/webpack-plugin？

在项目目录运行 npm install @appshell/webpack-plugin，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：webpack（^5\.106\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @appshell/webpack-plugin 支持 TypeScript 吗？

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

### @appshell/webpack-plugin 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @appshell/webpack-plugin 可以商用吗？

@appshell/webpack-plugin 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @appshell/webpack-plugin 的下载量有多少？

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

### @appshell/webpack-plugin 还在维护吗？

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