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

# output.externals

- **类型：**

```ts
type Externals =
  | string
  | object
  | function
  | RegExp
  | Array<string | object | function | RegExp>;
```

- **默认值：** `undefined`

用于指定哪些模块不需要被 Rsbuild 打包，而是直接使用外部环境中提供的实现。

例如，当页面已经通过 CDN 引入了 React，或你开发的库希望由使用方自行安装 `react` 时，可以将其声明为 external。这可以减少打包产物的体积，同时避免重复引入相同依赖。

该能力常用于库开发场景，同时在应用侧接入 CDN、使用宿主环境注入依赖等场景中也同样适用。

> 更多用法请参考 Rspack 的 [Externals](https://rspack.rs/zh/config/externals) 文档。

## 示例

### 基础用法

例如，将 `react-dom` 从构建产物中排除，并在运行时通过全局变量 `ReactDOM` 来获取该模块：

```ts title="rsbuild.config.ts"
export default {
  output: {
    externals: {
      'react-dom': 'ReactDOM',
      'react-dom/client': 'ReactDOM',
    },
  },
};
```

值得注意的是，当在 `externals` 中以字符串形式指定模块名时，匹配规则为精确匹配。因此需要显式声明 `react-dom/client` 等子路径导入。

如果你需要匹配一组相似的导入形式，可以改用[正则表达式](#regular-expressions)，或者使用函数来实现更灵活的匹配逻辑。

### 数组格式

使用数组来定义多个 `externals` 配置：

```ts title="rsbuild.config.ts"
export default {
  output: {
    externals: [
      {
        react: 'React',
        'react-dom': 'ReactDOM',
      },
      'lodash',
    ],
  },
};
```

### 配合 CDN 使用

一个常见的用法是从 CDN 加载一些库，将它们从构建产物中排除，通过 [html.tags](/zh/config/html/tags.md) 配置将它们引入到 HTML 中。

```ts title="rsbuild.config.ts"
export default {
  output: {
    externals: {
      axios: 'axios',
    },
  },
  html: {
    tags: [
      {
        tag: 'script',
        append: false,
        attrs: {
          defer: true,
          crossorigin: true,
          src: 'https://unpkg.com/axios@1/dist/axios.min.js',
        },
      },
    ],
  },
};
```

然后，你可以在源代码中使用外部库：

```js title="src/api.js"
const response = await window.axios.get('/api/users');
```

### 正则表达式 \{#regular-expressions}

使用正则表达式来匹配具有特定模式的多个模块：

```ts title="rsbuild.config.ts"
export default {
  output: {
    externals: [
      // 外部化所有 @babel 包
      /^@babel\/.+$/,
      // 外部化所有 lodash 子模块
      /^lodash\/.+$/,
    ],
  },
};
```

## Web workers

当 [output.target](/zh/config/output/target.md) 为 `web-worker` 时，外部依赖需要由 worker 自身的运行环境提供。Worker 无法访问主页面的全局变量。

对于 module worker 产物（[output.module](/zh/config/output/module.md) 为 `true`），外部依赖默认通过 ES 模块导入加载。请确保 worker 运行时能够解析外部模块的路径。

对于 classic worker 产物（`output.module: false`），可以将依赖映射到 worker 内的全局变量。例如，将 `worker-sdk` 映射到 `self.WorkerSDK`：

```ts title="rsbuild.config.ts"
export default {
  output: {
    target: 'web-worker',
    module: false,
    externals: {
      'worker-sdk': 'self WorkerSDK',
    },
  },
};
```

在加载 worker 产物前，需要先加载定义 `self.WorkerSDK` 的脚本。例如，在单独的启动脚本中调用 `importScripts()`，先加载依赖脚本，再加载 worker 产物。

:::tip
如果同时构建 `web` 和 `web-worker` 两种 target，请将依赖浏览器页面全局变量的 externals 配置在 `target: 'web'` 对应的[环境](/zh/config/environments.md)中。不要放在顶层 `output.externals` 中，因为顶层配置也会应用到 worker，而 worker 无法访问页面中的全局变量。
:::