output.externals

类型：

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

默认值： undefined

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

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

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

更多用法请参考 Rspack 的 Externals 文档。

示例

基础用法

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

rsbuild.config.ts

export default {
  output: {
    externals: {
      'react-dom': 'ReactDOM',
      'react-dom/client': 'ReactDOM',
    },
  },
};

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

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

数组格式

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

rsbuild.config.ts

export default {
  output: {
    externals: [
      {
        react: 'React',
        'react-dom': 'ReactDOM',
      },
      'lodash',
    ],
  },
};

配合 CDN 使用

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

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',
        },
      },
    ],
  },
};

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

src/api.js

const response = await window.axios.get('/api/users');

正则表达式

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

rsbuild.config.ts

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

Web workers

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

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

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

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' 对应的环境中。不要放在顶层 output.externals 中，因为顶层配置也会应用到 worker，而 worker 无法访问页面中的全局变量。

#output.externals

#示例

#基础用法

#数组格式

#配合 CDN 使用

#正则表达式

#Web workers

output.externals

示例

基础用法

数组格式

配合 CDN 使用

正则表达式

Web workers