#BannerPlugin

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

#示例

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

import { rspack } from '@rspack/core';

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

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

/*! Built with Rspack */
// ...

#选项

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

#banner

• 类型：

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

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

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

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

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

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

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

#entryOnly

• 类型： boolean
• 默认值： undefined

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

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

#footer

• 类型： boolean
• 默认值： undefined

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

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

#raw

• 类型： boolean
• 默认值： undefined

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

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

#stage

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

控制添加 banner 时所处的 processAssets 阶段。数值越小，执行越早。仅当 banner 需要在另一个处理资源的插件之前或之后运行时，才需要修改此选项。

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 文件。

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

#include

• 类型： string | RegExp | Array<string | RegExp>
• 默认值： undefined

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

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

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

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 完成筛选后应用。

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