- **类型：** `Function | undefined`
- **默认值：** `undefined`

你可以通过 `tools.bundlerChain` 来修改默认的 webpack 和 Rspack 配置，它的值为 `Function` 类型，接收两个参数：

- 第一个参数为 `bundler-chain` 对象实例，你可以通过这个实例来修改 webpack 和 Rspack 的配置。
- 第二个参数为一个工具集合，包括`env`、`isProd`、`CHAIN_ID` 等。

:::tip 什么是 BundlerChain

Bundler chain 是 webpack chain 的子集，其中包含一部分 webpack chain API，你可以用它来同时修改 webpack 和 Rspack 的配置。

通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个[Rspack 兼容](https://www.rspack.dev/zh/guide/plugin-compat.html)的 webpack 插件。

:::

> `tools.bundlerChain` 的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack，因此会被其他几个配置中的修改所覆盖。

### 工具集合

#### env

- **类型：** `'development' | 'production' | 'test'`

通过 env 参数可以判断当前环境为 development、production 还是 test。比如：

```js
export default {
  tools: {
    bundlerChain: (chain, { env }) => {
      if (env === 'development') {
        chain.devtool('cheap-module-eval-source-map');
      }
    },
  },
};
```

#### isProd

- **类型：** `boolean`

通过 isProd 参数可以判断当前环境是否为 production。比如：

```js
export default {
  tools: {
    bundlerChain: (chain, { isProd }) => {
      if (isProd) {
        chain.devtool('source-map');
      }
    },
  },
};
```

#### target

- **类型：** `'web' | 'node' | 'modern-web' | 'web-worker'`

通过 target 参数可以判断当前构建的目标运行时环境。比如：

```js
export default {
  tools: {
    bundlerChain: (chain, { target }) => {
      if (target === 'node') {
        // ...
      }
    },
  },
};
```

#### isServer

- **类型：** `boolean`

判断当前构建的目标运行时环境是否为 `node`，等价于 `target === 'node'`。

```js
export default {
  tools: {
    bundlerChain: (chain, { isServer }) => {
      if (isServer) {
        // ...
      }
    },
  },
};
```

#### isWebWorker

- **类型：** `boolean`

判断当前构建的目标运行时环境是否为 `web-worker`，等价于 `target === 'web-worker'`。

```js
export default {
  tools: {
    bundlerChain: (chain, { isWebWorker }) => {
      if (isWebWorker) {
        // ...
      }
    },
  },
};
```

### HtmlPlugin

- **类型：** `typeof import('html-webpack-plugin') | import('@rspack/plugin-html') `

通过这个参数你可以拿到 webpack 或 Rspack 中的 HtmlPlugin 实例。

```js
export default {
  tools: {
    bundlerChain: (chain, { HtmlPlugin }) => {
      console.log(HtmlPlugin);
    },
  },
};
```

#### CHAIN_ID

Builder 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。

##### CHAIN_ID.RULE

| ID           | 描述               |
| ------------ | ------------------ |
| `RULE.MJS`   | 处理 `mjs` 的规则  |
| `RULE.CSS`   | 处理 `css` 的规则  |
| `RULE.LESS`  | 处理 `less` 的规则 |
| `RULE.SASS`  | 处理 `sass` 的规则 |
| `RULE.TOML`  | 处理 `toml` 的规则 |
| `RULE.YAML`  | 处理 `yaml` 的规则 |

### CHAIN_ID.ONE_OF

通过 `ONE_OF.XXX` 可以匹配到规则数组中的某一类规则。

| ID                  | 描述                                                |
| ------------------- | --------------------------------------------------- |
| `ONE_OF.SVG`        | 处理 SVG 的规则，在 data URI 和单独文件之间自动选择 |
| `ONE_OF.SVG_URL`    | 处理 SVG 的规则，输出为单独文件                     |
| `ONE_OF.SVG_INLINE` | 处理 SVG 的规则，作为 data URI 内联到 bundle 中     |
| `ONE_OF.SVG_ASSETS` | 处理 SVG 的规则，在 data URI 和单独文件之间自动选择 |

### CHAIN_ID.USE

通过 `USE.XXX` 可以匹配到对应的 loader。

| ID                     | 描述                                  |
| ---------------------- | ------------------------------------- |
| `USE.LESS`             | 对应 `less-loader`                    |
| `USE.SASS`             | 对应 `sass-loader`                    |
| `USE.TOML`             | 对应 `toml-loader`                    |
| `USE.YAML`             | 对应 `yaml-loader`                    |
| `USE.SVGR`             | 对应 `@svgr/webpack`                  |
| `USE.POSTCSS`          | 对应 `postcss-loader`                 |

### CHAIN_ID.PLUGIN

通过 `PLUGIN.XXX` 可以匹配到对应的 plugin。

| ID                             | 描述                                                                               |
| ------------------------------ | ---------------------------------------------------------------------------------- |
| `PLUGIN.HTML`                  | 对应 `HtmlPlugin`，使用时需要拼接 entry 名称：`${PLUGIN.HTML}-${entryName}` |
| `PLUGIN.APP_ICON`              | 对应 `AppIconPlugin`                                                               |
| `PLUGIN.INLINE_HTML`           | 对应 `InlineChunkHtmlPlugin`                                                       |
| `PLUGIN.BUNDLE_ANALYZER`       | 对应 `WebpackBundleAnalyzer`                                                       |
| `PLUGIN.BOTTOM_TEMPLATE`       | 对应 `BottomTemplatePlugin`                                                        |
| `PLUGIN.ASSETS_RETRY`          | 对应 Builder 中的 webpack 静态资源重试插件 `WebpackAssetsRetryPlugin`              |
| `PLUGIN.AUTO_SET_ROOT_SIZE`    | 对应 Builder 中的自动设置根字体大小插件 `AutoSetRootSizePlugin`                    |

### 常用 BundlerChain 使用示例

BundlerChain 的使用可参考：[常用 WebpackChain 使用示例](https://modernjs.dev/builder/guide/advanced/custom-webpack-config.html#%E4%BD%BF%E7%94%A8-webpack-chain)。
