> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# ExternalsPlugin

`ExternalsPlugin` 将指定依赖排除在 bundle 之外，并生成在运行时访问这些依赖的代码。例如，外部依赖可以通过 ES 模块 `import` 引用，也可以来自其他脚本提供的浏览器全局变量。

对于大多数项目，直接配置 [`externals`](/zh/config/externals.md) 和 [`externalsType`](/zh/config/externals.md#externalstype) 即可，Rspack 会在内部应用 `ExternalsPlugin`。如果需要在其他插件中添加外部依赖规则，或通过多个插件实例分别设置 `externalsType`，可以直接使用该插件。

## 示例 \{#examples}

### ESM 导入 \{#esm-imports}

启用 [`output.module`](/zh/config/output.md#outputmodule)，并将 `externalsType` 设为 `'module'`，可以将 `react` 排除在 bundle 之外，同时在产物中生成对它的 ES 模块导入：

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  output: {
    module: true,
  },
  plugins: [new rspack.ExternalsPlugin('module', ['react'])],
};
```

产物的使用方需要能够解析 `react` 导入。例如，后续的打包工具可以解析它，浏览器也可以通过 import map 将它映射到 URL。字符串规则只会精确匹配 `react`，不会匹配 `react/jsx-runtime` 等子路径。

对于这个例子，对应的配置项写法是：

```js title="rspack.config.mjs"
export default {
  output: {
    module: true,
  },
  externalsType: 'module',
  externals: ['react'],
};
```

### 浏览器全局变量 \{#browser-globals}

如果页面已经通过脚本加载 Lodash，并提供了 `window._`，可以将 `lodash` 请求映射到这个全局变量：

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.ExternalsPlugin('window', { lodash: '_' })],
};
```

应用代码仍然可以使用 `import _ from 'lodash'`。bundle 会读取 `window._`，而不包含 Lodash，因此应先加载提供该变量的脚本，再执行 bundle。

## 选项 \{#options}

第一个参数指定 `externalsType`，第二个参数 `externals` 指定匹配规则：

```js
new rspack.ExternalsPlugin(externalsType, externals);
```

### externalsType

- **类型：** `ExternalsType`
- **是否必填：** 是

决定运行时如何访问匹配的依赖。

应根据产物格式和运行环境选择 `externalsType`。完整的可选值及其使用条件见 [`externalsType`](/zh/config/externals.md#externalstype)。

单条规则可以在结果中添加类型前缀，以覆盖 `externalsType`：

```js
new rspack.ExternalsPlugin('module', {
  react: 'react',
  lodash: 'window _',
});
```

在启用 `output.module` 时，`react` 通过 ES 模块导入，而 `lodash` 从 `window._` 读取。

### externals

- **类型：** `Externals`
- **是否必填：** 是

指定哪些模块请求应作为外部依赖，以及如何引用它们。规则匹配的是源码中的模块请求，此时请求尚未被解析为文件路径。

支持的规则形式和值格式见 [`externals` 配置参考](/zh/config/externals.md)。如需自定义匹配逻辑或解析请求，见[函数形式](/zh/config/externals.md#function)。