close
  • 简体中文

      • 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\/.+$/,
    ],
  },
};
      Tip

      当 output.target 为 web-worker 时，externals 将不会生效。这是因为 Web Worker 环境不支持访问全局变量。