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

# BannerPlugin

`BannerPlugin` 用于在生成的 chunk 文件开头或结尾插入指定内容。默认情况下，它会将指定内容包裹成注释，并插入每个 chunk 文件的开头。

## 示例

在每个生成的 chunk 文件开头添加一段注释：

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

export default {
  plugins: [new rspack.BannerPlugin('Built with Rspack')],
};
```

生成的 chunk 文件会以这段注释开头：

```js title="dist/main.js"
/*! Built with Rspack */
// ...
```

## 选项

`BannerPlugin` 可以接收 banner 字符串、函数或选项对象。下面的示例沿用上方导入的 `rspack`。

### banner

- **类型：**

  ```ts
  type BannerFunction = (args: {
    hash: string;
    chunk: Chunk;
    filename: string;
  }) => string;

  type BannerContent = string | BannerFunction;
  ```

- **是否必填：** 使用选项对象时必填

`banner` 选项支持以下两种形式：

- **字符串：** 传入字符串可直接指定 banner 内容。默认情况下，Rspack 会将字符串包裹成注释。可以通过 `banner` 选项设置，也可以直接将字符串传给 `BannerPlugin`。

  ```js
  new rspack.BannerPlugin({
    banner: 'Built with Rspack',
  });
  ```

- **函数：** 需要为每个选中的 chunk 文件动态生成 banner 时，可以传入函数。Rspack 调用函数时会传入本次编译的 `hash`、当前 `chunk` 和产物文件名 `filename`。函数返回的字符串默认会被包裹成注释。可以通过 `banner` 选项设置，也可以直接将函数传给 `BannerPlugin`。

  ```js
  new rspack.BannerPlugin({
    banner: ({ filename }) => `Built file: ${filename}`,
  });
  ```

### entryOnly

- **类型：** `boolean`
- **默认值：** `undefined`

设置为 `true` 时，只在初始 chunk 的文件中添加 banner，并跳过异步加载的 chunk 文件。省略时，初始 chunk 和异步 chunk 的文件均可添加 banner。

```js
new rspack.BannerPlugin({
  banner: 'Entry bundle',
  entryOnly: true,
});
```

### footer

- **类型：** `boolean`
- **默认值：** `undefined`

设置为 `true` 时，将 banner 追加到每个选中的 chunk 文件末尾，而不是添加到开头。省略时，banner 会添加到文件开头。

```js
new rspack.BannerPlugin({
  banner: 'End of bundle',
  footer: true,
});
```

### raw

- **类型：** `boolean`
- **默认值：** `undefined`

设置为 `true` 时，输出 banner 时不将其包裹成注释。请确保原始内容对每个选中的输出文件都是有效的。

```js
new rspack.BannerPlugin({
  banner: '/* Build: production */',
  raw: true,
});
```

### stage

- **类型：** `number`
- **默认值：** `Compilation.PROCESS_ASSETS_STAGE_ADDITIONS`（`-100`）

控制添加 banner 时所处的 [`processAssets`](/zh/api/plugin-api/compilation-hooks.md#processassets) 阶段。数值越小，执行越早。仅当 banner 需要在另一个处理资源的插件之前或之后运行时，才需要修改此选项。

```js
new rspack.BannerPlugin({
  banner: 'Optimized bundle',
  stage: rspack.Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE,
});
```

### test

- **类型：** `string | RegExp | Array<string | RegExp>`
- **默认值：** `undefined`

`test` 用于筛选需要添加 banner 的 chunk 文件。仅当 chunk 的产物文件名与 `test` 匹配时，才会添加 banner。

匹配对象是产物文件名，而不是模块源码路径。字符串匹配文件名开头；正则表达式可匹配任意位置；传入数组时，任一条件匹配即可。

省略 `test` 时，不会通过该选项过滤 chunk 文件。

```js
new rspack.BannerPlugin({
  banner: 'JavaScript bundle',
  test: /\.js$/,
});
```

### include

- **类型：** `string | RegExp | Array<string | RegExp>`
- **默认值：** `undefined`

`include` 用于限定需要添加 banner 的 chunk 文件。仅当 chunk 的产物文件名与 `include` 匹配时，才会添加 banner。

匹配对象是产物文件名，而不是模块源码路径。字符串匹配文件名开头；正则表达式可匹配任意位置；传入数组时，任一条件匹配即可。

如果同时设置 `test`，产物文件名必须同时满足 `test` 和 `include`。

```js
new rspack.BannerPlugin({
  banner: 'Application bundle',
  include: [/^app/, /^admin/],
});
```

### exclude

- **类型：** `string | RegExp | Array<string | RegExp>`
- **默认值：** `undefined`

`exclude` 用于指定不添加 banner 的 chunk 文件。如果 chunk 的产物文件名与 `exclude` 匹配，则不会添加 banner。

匹配对象是产物文件名，而不是模块源码路径。字符串匹配文件名开头；正则表达式可匹配任意位置；传入数组时，任一条件匹配即可。

`exclude` 会在 `test` 和 `include` 完成筛选后应用。

```js
new rspack.BannerPlugin({
  banner: 'Application bundle',
  exclude: [/^runtime/, /^vendor/],
});
```