AutomaticPrefetchPlugin

AutomaticPrefetchPlugin 在观察更改时，会预先发现先前编译中的**所有模块**，以尝试改进增量构建时间。相比之下，PrefetchPlugin 预先发现的是**单个模块**。

webpack.config.js

module.exports = {
  // ...
  plugins: [new webpack.AutomaticPrefetchPlugin()],
};

BannerPlugin

在每个生成的 chunk 顶部添加一个 banner。

const webpack = require('webpack');

new webpack.BannerPlugin(banner);
// or
new webpack.BannerPlugin(options);

选项

{
  banner: string | function, // the banner as string or function, it will be wrapped in a comment
  raw: boolean, // if true, banner will not be wrapped in a comment
  entryOnly: boolean, // if true, the banner will only be added to the entry chunks
  test: string | RegExp | [string, RegExp], // Include all modules that pass test assertion.
  include: string | RegExp | [string, RegExp], // Include all modules matching any of these conditions.
  exclude: string | RegExp | [string, RegExp], // Exclude all modules matching any of these conditions.
  footer?: boolean, // if true, the banner will be placed at the end of the compilation
  stage?: number, // the stage of the compilation in which the banner should be injected
}

用法

import webpack from 'webpack';

// string
new webpack.BannerPlugin({
  banner: 'hello world',
});

// function
new webpack.BannerPlugin({
  banner: (yourVariable) => {
    return `yourVariable: ${yourVariable}`;
  },
});

// It will add the banner message after minimizers and any asset manipulation
new webpack.BannerPlugin({
  raw: true,
  banner: '/* banner is a string */',
  stage: webpack.Compilation.PROCESS_ASSETS_STAGE_REPORT,
});

占位符

从 webpack 2.5.0 开始，占位符在 banner 字符串中进行求值。

import webpack from 'webpack';

new webpack.BannerPlugin({
  banner:
    'fullhash:[fullhash], chunkhash:[chunkhash], name:[name], filebase:[filebase], query:[query], file:[file]',
});

ChunksWebpackPlugin

chunks-webpack-plugin 创建包含入口点和 chunk 关系的 HTML 文件，用于服务你的 webpack bundles。它适用于包含多个入口点的多页面应用程序。

从 webpack 4 开始，SplitChunksPlugin 提供了优化所有 chunk 的可能性。它可能特别强大，因为这意味着 chunk 甚至可以在异步和非异步 chunk 之间共享。有关详细信息，请参阅 webpack 文档中的 splitChunks.chunks。

splitChunks.chunks 选项可以设置为自动生成与入口点关联的新 chunk。例如，入口点 a.js 和 b.js 与文件 vendors~a~b.js 共享通用代码。

在有多个入口点的情况下，识别自动生成的 chunk 和入口点之间的关系可能很困难。

chunks-webpack-plugin 解析 webpack 编译的入口点以获取与入口点关联的所有文件。然后，它生成 HTML 文件，其中包含按入口点筛选的所有资产和 chunks-manifest.json 文件。

零配置

它无需配置即可工作。对于高级用法，请参阅使用配置部分。

安装

chunks-webpack-plugin 在 npm 上可用，名称为 chunks-webpack-plugin，在 GitHub 上也可用，名称为 chunks-webpack-plugin。

npm install chunks-webpack-plugin --save-dev

yarn add chunks-webpack-plugin --dev

[!WARNING] 插件 chunks-webpack-plugin@10 仅支持 ESM。 [!NOTE] 支持的最低 Node.js 版本为 16.20.0，Webpack 版本为 >=5.10.3。

示例

该项目在 ./example 目录中包含一个极简示例。运行 npm run build:example 命令以执行 Webpack 示例并查看插件的实际实现。

基本用法

chunks-webpack-plugin 将为每个入口点生成两个 HTML 文件。每个文件名都包含入口点名称，{{entry}} 占位符会自动替换。

• {{entry}}-styles.html：包含所有 HTML <link> 标签
• {{entry}}-scripts.html：包含所有 HTML <script> 标签

首先，将插件添加到 webpack 配置中。

webpack.config.js

import ChunksWebpackPlugin from 'chunks-webpack-plugin';

export default {
  plugins: [new ChunksWebpackPlugin()]
};

HTML 文件与 webpack 编译的其余部分一起构建在输出路径目录中。

现在你可以将生成的 HTML 文件包含到你的 HTML 页面模板中。你可以通过 Twig 等方式实现。

main-styles.html

<link rel="stylesheet" href="main.css" />

main-scripts.html

<script defer src="main.js"></script>

使用配置

你可以向 chunks-webpack-plugin 传递一个配置对象来覆盖默认设置。

filename

类型

type filename = string;

默认值：'[name]-[type].html'

指示插件是否个性化生成文件的文件名。文件由 webpack 编译处理并在输出路径目录中生成。占位符 [name] 会自动替换为入口点名称，[type] 会替换为 styles|scripts。

new ChunksWebpackPlugin({
  filename: 'templates/[name]-[type].html'
});

[!NOTE] filename 可以包含目录，这些目录将自动创建。

templateStyle

类型

type templateStyle = (name: string, entryName: string) => string;

默认值

(name) => `<link rel="stylesheet" href="${name}" />`;

指示插件是否个性化 HTML <style> 标签的默认模板。例如，添加额外的属性或 CDN 前缀。

export default {
  plugins: [
    new ChunksWebpackPlugin({
      templateStyle: (name) => `<link rel="stylesheet" href="https://cdn.domain.com${name}" />`
    })
  ]
};

templateScript

类型

type templateScript = (name: string, entryName: string) => string;

默认值

(name) => `<script defer src="${name}"></script>`;

指示插件是否个性化 HTML <script> 标签的默认模板。例如，添加额外的属性或 CDN 前缀。

export default {
  plugins: [
    new ChunksWebpackPlugin({
      templateScript: (name) => `<script defer src="https://cdn.domain.com${name}"></script>`
    })
  ]
};

generateChunksManifest

类型

type generateChunksManifest = boolean;

默认值：false

指示插件是否生成 chunks-manifest.json。该文件包含按入口点分组的所有 chunk 列表。请参阅 chunks-manifest.json 示例。

export default {
  plugins: [
    new ChunksWebpackPlugin({
      generateChunksManifest: true
    })
  ]
};

generateChunksFiles

类型

type generateChunksFiles = boolean;

默认值：true

指示插件是否生成 HTML 文件。

export default {
  plugins: [
    new ChunksWebpackPlugin({
      generateChunksFiles: false
    })
  ]
};

[!WARNING] 当设置为 false 时，HTML 文件将不会生成。它仅在 generateChunksManifest 选项设置为 true 并用于自定义生成 HTML 文件时才有用。

import ChunksWebpackPlugin from 'chunks-webpack-plugin';
import path from 'node:path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default {
  entry: {
    home: 'home.js',
    news: 'news.js'
  },
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, './dist')
  },
  plugins: [new ChunksWebpackPlugin()],
  optimization: {
    splitChunks: {
      chunks: 'all'
    }
  }
};

<link rel="stylesheet" href="vendors~home~news.css" />
<link rel="stylesheet" href="home.css" />

<script defer src="vendors~home~news.js"></script>
<script defer src="home.js"></script>

<link rel="stylesheet" href="vendors~home~news.css" />
<link rel="stylesheet" href="news.css" />

<script defer src="vendors~home~news.js"></script>
<script defer src="news.js"></script>

许可证

chunks-webpack-plugin 根据 MIT 许可证获得许可。

由 @yoriiis 用 ♥ 创建。

CommonsChunkPlugin

CommonsChunkPlugin 是一个选择加入的功能，它创建一个单独的文件（称为 chunk），由多个入口点之间共享的通用模块组成。

通过将通用模块从 bundles 中分离出来，生成的 chunked 文件可以最初加载一次，并存储在缓存中供以后使用。这会带来页面速度优化，因为浏览器可以从缓存中快速提供共享代码，而无需在每次访问新页面时都被迫加载更大的 bundle。

new webpack.optimize.CommonsChunkPlugin(options);

选项

{
  name: string, // or
  names: string[],
  // The chunk name of the commons chunk. An existing chunk can be selected by passing a name of an existing chunk.
  // If an array of strings is passed this is equal to invoking the plugin multiple times for each chunk name.
  // If omitted and `options.async` or `options.children` is set all chunks are used, otherwise `options.filename`
  // is used as chunk name.
  // When using `options.async` to create common chunks from other async chunks you must specify an entry-point
  // chunk name here instead of omitting the `option.name`.

  filename: string,
  // The filename template for the commons chunk. Can contain the same placeholders as `output.filename`.
  // If omitted the original filename is not modified (usually `output.filename` or `output.chunkFilename`).
  // This option is not permitted if you're using `options.async` as well, see below for more details.

  minChunks: number|Infinity|function(module, count) => boolean,
  // The minimum number of chunks which need to contain a module before it's moved into the commons chunk.
  // The number must be greater than or equal 2 and lower than or equal to the number of chunks.
  // Passing `Infinity` creates the commons chunk, but moves no modules into it.
  // By providing a `function` you can add custom logic. (Defaults to the number of chunks)

  chunks: string[],
  // Select the source chunks by chunk names. The chunk must be a child of the commons chunk.
  // If omitted all entry chunks are selected.

  children: boolean,
  // If `true` all children of the commons chunk are selected

  deepChildren: boolean,
  // If `true` all descendants of the commons chunk are selected

  async: boolean|string,
  // If `true` a new async commons chunk is created as child of `options.name` and sibling of `options.chunks`.
  // It is loaded in parallel with `options.chunks`.
  // Instead of using `option.filename`, it is possible to change the name of the output file by providing
  // the desired string here instead of `true`.

  minSize: number,
  // Minimum size of all common module before a commons chunk is created.
}

示例

入口点的公共 chunk

生成一个额外的 chunk，其中包含入口点之间共享的通用模块。

new webpack.optimize.CommonsChunkPlugin({
  name: 'commons',
  // (the commons chunk name)

  filename: 'commons.js',
  // (the filename of the commons chunk)

  // minChunks: 3,
  // (Modules must be shared between 3 entries)

  // chunks: ["pageA", "pageB"],
  // (Only use these entries)
});

你必须在入口点之前加载生成的 chunk。

<script src="commons.js" charset="utf-8"></script>
<script src="entry.bundle.js" charset="utf-8"></script>

显式供应商 chunk

将你的代码拆分为供应商和应用程序部分。

module.exports = {
  //...
  entry: {
    vendor: ['jquery', 'other-lib'],
    app: './entry',
  },
  plugins: [
    new webpack.optimize.CommonsChunkPlugin({
      name: 'vendor',
      // filename: "vendor.js"
      // (Give the chunk a different name)

      minChunks: Infinity,
      // (with more entries, this ensures that no other module
      //  goes into the vendor chunk)
    }),
  ],
};

<script src="vendor.js" charset="utf-8"></script>
<script src="app.js" charset="utf-8"></script>

将通用模块移入父 chunk

通过代码分割，入口 chunk 的多个子 chunk 可以拥有共同的依赖。为了防止重复，这些依赖可以移入父 chunk。这会减少总体大小，但会对初始加载时间产生负面影响。如果预计用户需要下载许多兄弟 chunk（即入口 chunk 的子 chunk），那么这应该会总体上改善加载时间。

new webpack.optimize.CommonsChunkPlugin({
  // names: ["app", "subPageA"]
  // (choose the chunks, or omit for all chunks)

  children: true,
  // (select all children of chosen chunks)

  // minChunks: 3,
  // (3 children must share the module before it's moved)
});

额外的异步公共 chunk

与上述类似，但不是将通用模块移入父 chunk（这会增加初始加载时间），而是使用一个新的异步加载的额外通用 chunk。当下载额外的 chunk 时，它会自动并行下载。

new webpack.optimize.CommonsChunkPlugin({
  name: 'app',
  // or
  names: ['app', 'subPageA'],
  // the name or list of names must match the name or names
  // of the entry points that create the async chunks

  children: true,
  // (use all children of the chunk)

  async: true,
  // (create an async commons chunk)

  minChunks: 3,
  // (3 children must share the module before it's separated)
});

将函数传递给 minChunks 属性

你还可以将函数传递给 minChunks 属性。此函数由 CommonsChunkPlugin 调用，并以 module 和 count 参数调用该函数。

module 参数表示你通过 name/names 属性提供的 chunk 中的每个模块。module 具有 NormalModule 的形状，其中有两个特别有用的属性适用于此用例：

• module.context：存储文件的目录。例如：'/my_project/node_modules/example-dependency'
• module.resource：正在处理的文件名。例如：'/my_project/node_modules/example-dependency/index.js'

count 参数表示 module 在多少个 chunk 中被使用。

当您希望对 CommonsChunk 算法如何确定模块应移动到何处进行细粒度控制时，此选项很有用。

new webpack.optimize.CommonsChunkPlugin({
  name: 'my-single-lib-chunk',
  filename: 'my-single-lib-chunk.js',
  minChunks: function (module, count) {
    // If module has a path, and inside of the path exists the name "somelib",
    // and it is used in 3 separate chunks/entries, then break it out into
    // a separate chunk with chunk keyname "my-single-lib-chunk", and filename "my-single-lib-chunk.js"
    return module.resource && /somelib/.test(module.resource) && count === 3;
  },
});

如上所示，此示例允许你仅在函数内满足所有条件时才将一个库移动到单独的文件中。

此概念可用于获取隐式通用供应商 chunk。

new webpack.optimize.CommonsChunkPlugin({
  name: 'vendor',
  minChunks: function (module) {
    // this assumes your vendor imports exist in the node_modules directory
    return module.context && module.context.includes('node_modules');
  },
});

清单文件

要将 webpack 引导逻辑提取到单独的文件中，请对未定义为 entry 的 name 使用 CommonsChunkPlugin。通常使用名称 manifest。有关详细信息，请参阅缓存指南。

new webpack.optimize.CommonsChunkPlugin({
  name: 'manifest',
  minChunks: Infinity,
});

结合隐式通用供应商 chunk 和清单文件

由于 vendor 和 manifest chunk 使用不同的 minChunks 定义，你需要两次调用插件。

[
  new webpack.optimize.CommonsChunkPlugin({
    name: 'vendor',
    minChunks: function (module) {
      return module.context && module.context.includes('node_modules');
    },
  }),
  new webpack.optimize.CommonsChunkPlugin({
    name: 'manifest',
    minChunks: Infinity,
  }),
];

更多示例

• 通用和供应商 chunk
• 多个通用 chunk
• 带通用 chunk 的多个入口点

CompressionWebpackPlugin

准备资产的压缩版本，以便使用 Content-Encoding 进行服务。

入门

首先，你需要安装 compression-webpack-plugin

npm install compression-webpack-plugin --save-dev

或

yarn add -D compression-webpack-plugin

或

pnpm add -D compression-webpack-plugin

然后将插件添加到你的 webpack 配置中。例如：

webpack.config.js

const CompressionPlugin = require("compression-webpack-plugin");

module.exports = {
  plugins: [new CompressionPlugin()],
};

最后，使用你通常使用的方法运行 webpack（例如，通过 CLI 或 npm 脚本）。

选项

• test
• include
• exclude
• algorithm
• compressionOptions
• threshold
• minRatio
• 文件名
• deleteOriginalAssets

test

类型

type test = string | RegExp | Array<string | RegExp>;

默认值：undefined

包含所有通过测试断言的资产。

webpack.config.js

module.exports = {
  plugins: [
    new CompressionPlugin({
      test: /\.js(\?.*)?$/i,
    }),
  ],
};

include

类型

type include = string | RegExp | Array<string | RegExp>;

默认值：undefined

包含所有符合这些条件之一的资产。

webpack.config.js

module.exports = {
  plugins: [
    new CompressionPlugin({
      include: /\/includes/,
    }),
  ],
};

exclude

类型

type exclude = string | RegExp | Array<string | RegExp>;

默认值：undefined

排除所有符合这些条件之一的资产。

webpack.config.js

module.exports = {
  plugins: [
    new CompressionPlugin({
      exclude: /\/excludes/,
    }),
  ],
};

algorithm

类型

type algorithm =
  | string
  | ((
      input: Buffer,
      options: CompressionOptions,
      callback: (
        error: Error | null | undefined,
        result:
          | string
          | ArrayBuffer
          | SharedArrayBuffer
          | Uint8Array
          | readonly number[]
          | {
              valueOf(): ArrayBuffer | SharedArrayBuffer;
            }
          | {
              valueOf(): string | Uint8Array | readonly number[];
            }
          | {
              valueOf(): string;
            }
          | {
              [Symbol.toPrimitive](hint:%20%22string%22): string;
            },
      ) => void,
    ) => any);

定义要使用的压缩算法或函数。默认为 gzip。

[!注意]

如果你为 algorithm 选项使用自定义函数，则 compressionOptions 的默认值将为空对象 {}。

string

该算法基于 Node.js zlib 模块。

webpack.config.js

module.exports = {
  plugins: [
    new CompressionPlugin({
      algorithm: "gzip",
    }),
  ],
};

function

允许你指定自定义压缩函数。

webpack.config.js

module.exports = {
  plugins: [
    new CompressionPlugin({
      algorithm(input, compressionOptions, callback) {
        return compressionFunction(input, compressionOptions, callback);
      },
    }),
  ],
};

compressionOptions

类型

type compressionOptions = {
  flush?: number;
  finishFlush?: number;
  chunkSize?: number;
  windowBits?: number;
  level?: number;
  memLevel?: number;
  strategy?: number;
  dictionary?: Buffer | TypedArray | DataView | ArrayBuffer;
  info?: boolean;
  maxOutputLength?: number;
};

默认值：{ level: 9 }

algorithm 的压缩选项。

你可以在 zlib 文档中找到所有可用选项。

[!注意]

如果你为 algorithm 选项使用自定义函数，则 compressionOptions 的默认值将为空对象 {}。

webpack.config.js

module.exports = {
  plugins: [
    new CompressionPlugin({
      compressionOptions: { level: 1 },
    }),
  ],
};

threshold

类型

type threshold = number;

默认值：0

仅处理大于此大小（以字节为单位）的资产。

webpack.config.js

module.exports = {
  plugins: [
    new CompressionPlugin({
      threshold: 8192,
    }),
  ],
};

minRatio

类型

type minRatio = number;

默认值：0.8

仅处理压缩率优于此比率的资产（minRatio = 压缩大小 / 原始大小）。例如，如果你有一个大小为 1024 字节的 image.png 文件，并且其压缩版本为 768 字节，则 minRatio 为 0.75。换句话说，只有当 压缩大小 / 原始大小 的比率小于指定的 minRatio 时，才会处理资产。

你可以使用值 1 来处理小于或等于原始大小的资产。

使用值 Infinity 来处理所有资产，即使它们大于原始大小或其原始大小为 0 字节（当你为 AWS 预压缩所有资产时很有用）。

使用值 Number.MAX_SAFE_INTEGER 来处理所有资产，即使它们大于原始大小，但不包括原始大小为 0 字节的资产。

webpack.config.js

module.exports = {
  plugins: [
    new CompressionPlugin({
      // Compress all assets, including files with `0` bytes size
      // minRatio: Infinity

      // Compress all assets, excluding files with `0` bytes size
      // minRatio: Number.MAX_SAFE_INTEGER

      minRatio: 0.8,
    }),
  ],
};

filename

类型

type filename = string | ((pathdata: PathData) => string);

默认值："[path][base].gz"

目标资产文件名。

string

例如，给定资产路径：assets/images/image.png?foo=bar#hash

[path] 被原始资产的目录替换，包括尾随的 / (assets/images/)。

[file] 被原始资产的路径替换 (assets/images/image.png)。

[base] 被原始资产的基本名称 ([name] + [ext]) 替换 (image.png)。

[name] 被原始资产的名称替换 (image)。

[ext] 被原始资产的扩展名替换，包括 . (.png)。

[query] 被原始资产的查询部分替换，包括 ? (?foo=bar)。

[fragment] 被原始资产的片段（在 URL 概念中称为 hash）替换 (#hash)。

webpack.config.js

module.exports = {
  plugins: [
    new CompressionPlugin({
      filename: "[path][base].gz",
    }),
  ],
};

function

webpack.config.js

module.exports = {
  plugins: [
    new CompressionPlugin({
      filename(pathData) {
        // The `pathData` argument contains all placeholders - `path`/`name`/`ext`/etc
        // Available properties described above, for the `String` notation
        if (/\.svg$/.test(pathData.filename)) {
          return "assets/svg/[path][base].gz";
        }

        return "assets/js/[path][base].gz";
      },
    }),
  ],
};

deleteOriginalAssets

类型

type deleteOriginalAssets =
  | boolean
  | "keep-source-map"
  | ((name: string) => boolean);

默认值：false

确定原始（未压缩）资产是否应在压缩后删除。

• 如果设置为 true，所有原始资产都将被删除。

• 如果设置为 "keep-source-map"，所有原始资产（除了源映射文件 .map）都将被删除。

• 如果提供了函数，它将使用每个资产的名称进行调用，并且应返回 true 以删除资产，或返回 false 以保留资产。

示例

module.exports = {
  plugins: [
    new CompressionPlugin({
      deleteOriginalAssets: (assetName) => {
        // Delete all assets except images
        return !assetName.endsWith(".png") && !assetName.endsWith(".jpg");
      },
    }),
  ],
};

webpack.config.js

module.exports = {
  plugins: [
    new CompressionPlugin({
      deleteOriginalAssets: true,
    }),
  ],
};

排除源映射文件不进行压缩

module.exports = {
  plugins: [
    new CompressionPlugin({
      exclude: /.map$/,
      deleteOriginalAssets: "keep-source-map",
    }),
  ],
};

使用自定义函数

module.exports = {
  plugins: [
    new CompressionPlugin({
      exclude: /.map$/,
      deleteOriginalAssets: (name) => {
        if (/\.js$/.test(name)) {
          return false;
        }

        return true;
      },
    }),
  ],
};

示例

使用 Zopfli

使用 zopfli 库准备资产的压缩版本。

[!注意]

@gfx/zopfli 需要至少 Node.js 版本 8。

首先，你需要安装 @gfx/zopfli

$ npm install @gfx/zopfli --save-dev

webpack.config.js

const zopfli = require("@gfx/zopfli");

module.exports = {
  plugins: [
    new CompressionPlugin({
      compressionOptions: {
        numiterations: 15,
      },
      algorithm(input, compressionOptions, callback) {
        return zopfli.gzip(input, compressionOptions, callback);
      },
    }),
  ],
};

使用 Brotli

Brotli 是一种最初由 Google 开发的压缩算法，提供优于 gzip 的压缩效果。

Node.js v10.16.0 及更高版本在其 zlib 模块中包含了对 Brotli 压缩的原生支持。

你只需将适当的 algorithm 传递给 CompressionPlugin，即可利用 Node 10.16.0 及更高版本中内置的 Brotli 支持。

webpack.config.js

const zlib = require("zlib");

module.exports = {
  plugins: [
    new CompressionPlugin({
      filename: "[path][base].br",
      algorithm: "brotliCompress",
      test: /\.(js|css|html|svg)$/,
      compressionOptions: {
        params: {
          [zlib.constants.BROTLI_PARAM_QUALITY]: 11,
        },
      },
      threshold: 10240,
      minRatio: 0.8,
      deleteOriginalAssets: false,
    }),
  ],
};

[!NOTE] Brotli 的 BROTLI_PARAM_QUALITY 选项在功能上等同于 zlib 的 level 选项。你可以在 zlib 模块文档的相关部分中找到所有 Brotli 选项。

使用 Zstandard

Zstandard (zstd) 是一种快速的无损压缩算法，旨在实现 zlib 级别及更高的压缩比，适用于实时压缩场景。

Node.js 22.15.0 及更高版本在其 zlib 模块中包含了对 Zstandard 压缩的原生支持。

你只需将适当的 algorithm 传递给 CompressionPlugin，即可利用 Node 22.15.0 及更高版本中内置的 zstd 支持。

webpack.config.js

const zlib = require("zlib");

module.exports = {
  plugins: [
    new CompressionPlugin({
      filename: "[path][base].zst",
      algorithm: "zstdCompress",
      test: /\.(js|css|html|svg)$/,
      compressionOptions: {
        params: {
          [zlib.constants.ZSTD_c_compressionLevel]: 10,
        },
      },
      threshold: 10240,
      minRatio: 0.8,
      deleteOriginalAssets: false,
    }),
  ],
};

你可以在 zlib 模块文档的相关部分中找到所有 Zstandard 选项。

不同算法的多个压缩版本资产

webpack.config.js

const zlib = require("zlib");

module.exports = {
  plugins: [
    new CompressionPlugin({
      filename: "[path][base].gz",
      algorithm: "gzip",
      test: /\.js$|\.css$|\.html$/,
      threshold: 10240,
      minRatio: 0.8,
    }),
    new CompressionPlugin({
      filename: "[path][base].br",
      algorithm: "brotliCompress",
      test: /\.(js|css|html|svg)$/,
      compressionOptions: {
        params: {
          [zlib.constants.BROTLI_PARAM_QUALITY]: 11,
        },
      },
      threshold: 10240,
      minRatio: 0.8,
    }),
  ],
};

贡献

我们欢迎贡献！

如果你尚未阅读，请花一点时间阅读我们的贡献指南。

CONTRIBUTING

许可证

MIT

ContextExclusionPlugin

Context 指的是 带有表达式的 require，例如 require('./locale/' + name + '.json')。

ContextExclusionPlugin 允许你排除 context。在初始化插件时提供 RegExp 作为参数，以排除所有匹配的 context。

webpack.config.js

module.exports = {
  plugins: [new webpack.ContextExclusionPlugin(/dont/)],
};

ContextReplacementPlugin

Context 指的是 带有表达式的 require，例如 require('./locale/' + name + '.json')。当遇到此类表达式时，webpack 会推断出目录（'./locale/'）和正则表达式（/^.*\.json$/）。由于 name 在编译时未知，webpack 会将每个文件作为模块包含在 bundle 中。

ContextReplacementPlugin 允许你覆盖推断出的信息。配置插件有多种方式：

用法

new webpack.ContextReplacementPlugin(
  resourceRegExp: RegExp,
  newContentResource?: string,
  newContentRecursive?: boolean,
  newContentRegExp?: RegExp
)

如果资源（目录）与 resourceRegExp 匹配，插件会将默认资源、递归标志或生成的正则表达式分别替换为 newContentResource、newContentRecursive 或 newContextRegExp。如果 newContentResource 是相对路径，它将相对于前一个资源进行解析。

这是一个限制模块使用的小例子：

new webpack.ContextReplacementPlugin(/moment[/\\]locale$/, /de|fr|hu/);

moment/locale context 被限制为匹配 /de|fr|hu/ 的文件。因此，只包含这些 locales（有关详细信息，请参阅 此问题）。

内容回调

new webpack.ContextReplacementPlugin(
  resourceRegExp: RegExp,
  newContentCallback: (data) => void
);

newContentCallback 函数会获得一个 ContextModuleFactory 的 data 对象，并期望覆盖所提供对象的 request 属性。

使用此回调，我们可以动态地将请求重定向到新位置：

new webpack.ContextReplacementPlugin(/^\.\/locale$/, (context) => {
  if (!/\/moment\//.test(context.context)) return;

  Object.assign(context, {
    regExp: /^\.\/\w+/,
    request: '../../locale', // resolved relatively
  });
});

其他选项

newContentResource 和 newContentCreateContextMap 参数也可用。

new webpack.ContextReplacementPlugin(
  resourceRegExp: RegExp,
  newContentResource: string,
  newContentCreateContextMap: object // mapping runtime-request (userRequest) to compile-time-request (request)
);

这两个参数可以一起使用，以更具针对性的方式重定向请求。newContentCreateContextMap 允许你以对象形式将运行时请求映射到编译请求：

new ContextReplacementPlugin(/selector/, './folder', {
  './request': './request',
  './other-request': './new-request',
});

CopyWebpackPlugin

将现有单个文件或整个目录复制到构建目录。

入门

首先，你需要安装 copy-webpack-plugin

npm install copy-webpack-plugin --save-dev

或

yarn add -D copy-webpack-plugin

或

pnpm add -D copy-webpack-plugin

然后将插件添加到你的 webpack 配置中。例如：

webpack.config.js

const CopyPlugin = require("copy-webpack-plugin");

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        { from: "source", to: "dest" },
        { from: "other", to: "public" },
      ],
    }),
  ],
};

[!注意]

copy-webpack-plugin 不是设计用于复制构建过程中生成的文件。相反，它旨在复制已存在于源代码树中的文件，作为构建过程的一部分。

[!注意]

如果你希望 webpack-dev-server 在开发过程中将文件写入输出目录，你可以启用 writeToDisk 选项或使用 write-file-webpack-plugin。

[!注意]

你可以从 webpack stats API 中的 资产对象 获取原始源文件名。

选项

• patterns
• options

插件用法

webpack.config.js

const CopyPlugin = require("copy-webpack-plugin");

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        { from: "source", to: "dest" },
        "path/to/source", // Absolute or relative path, can be files, directories or globs. See examples below.
      ],
      options: {
        concurrency: 100,
      },
    }),
  ],
};

Patterns

• from
• to
• context
• globOptions
• filter
• toType
• force
• priority
• transform
• transformAll
• noErrorOnMissing
• info

from

类型

type from = string;

默认值：undefined

用于复制文件的 glob 模式或路径。Globs 遵循 fast-glob 模式语法。注意：Globs 必须是 string 类型。

[!警告]

如果 from 选项是 glob（即 path\to\file.ext），请不要直接在其中使用 \\，因为在 UNIX 系统上反斜杠被视为普通字符（而不是路径分隔符）。在 Windows 上，正斜杠和反斜杠都用作分隔符。请改用 /，或使用 Node 的 path 工具来规范化路径。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        "relative/path/to/file.ext",
        "relative/path/to/dir",
        path.resolve(__dirname, "src", "file.ext"),
        path.resolve(__dirname, "src", "dir"),
        "**/*",
        {
          from: "**/*",
        },
        // If absolute path is a `glob` we replace backslashes with forward slashes, because only forward slashes can be used in the `glob`
        path.posix.join(
          path.resolve(__dirname, "src").replace(/\\/g, "/"),
          "*.txt",
        ),
      ],
    }),
  ],
};

对于 Windows

如果你在 Windows 上使用 from 选项中的绝对文件或文件夹路径，可以使用 Windows 路径段（\\）

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: path.resolve(__dirname, "file.txt"),
        },
      ],
    }),
  ],
};

然而，在编写 glob 表达式时，始终使用正斜杠。有关更多详细信息，请参阅 fast-glob 手册。

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          // If absolute path is a `glob` we replace backslashes with forward slashes, because only forward slashes can be used in the `glob`
          from: path.posix.join(
            path.resolve(__dirname, "fixtures").replace(/\\/g, "/"),
            "*.txt",
          ),
        },
      ],
    }),
  ],
};

context 选项的行为取决于 from 值是 glob、file 还是 dir。请参阅更多 示例。

to

类型

type to =
  | string
  | ((pathData: { context: string; absoluteFilename?: string }) => string);

默认值：compiler.options.output

string

指定输出路径。

[!警告]

不要直接在 to 路径（例如 path\to\dest）选项中使用 \\，因为在 UNIX 系统上反斜杠被视为普通字符（而不是路径分隔符）。在 Windows 上，正斜杠和反斜杠都用作分隔符。请改用 /，或使用 Node 的 path 工具来规范化路径。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "**/*",
          to: "relative/path/to/dest/",
        },
        {
          from: "**/*",
          to: "/absolute/path/to/dest/",
        },
        {
          from: "**/*",
          to: "[path][name].[contenthash][ext]",
        },
      ],
    }),
  ],
};

function

允许修改写入路径。

[!警告]

不要直接在 to（即 path\to\newFile）选项中使用 \\，因为在 UNIX 系统上反斜杠被视为普通字符（而不是路径分隔符）。在 Windows 上，正斜杠和反斜杠都用作分隔符。请改用 /，或使用 Node 的 path 工具来规范化路径。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to({ context, absoluteFilename }) {
            return "dest/newPath/[name][ext]";
          },
        },
      ],
    }),
  ],
};

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to({ context, absoluteFilename }) {
            return Promise.resolve("dest/newPath/[name][ext]");
          },
        },
      ],
    }),
  ],
};

context

类型

type context = string;

默认值：options.context|compiler.options.context

定义用于两个目的的基本目录：

1. 它会添加到 from 路径的前面。

2. 它会从结果路径的开头移除。

[!警告]

不要直接在 to（即 path\to\newFile）选项中使用 \\，因为在 UNIX 系统上反斜杠被视为普通字符（而不是路径分隔符）。在 Windows 上，正斜杠和反斜杠都用作分隔符。请改用 /，或使用 Node 的 path 工具来规范化路径。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.txt",
          to: "dest/",
          context: "app/",
        },
      ],
    }),
  ],
};

context 可以是绝对路径或相对路径。如果是相对路径，则会根据 compiler.options.context 转换为绝对路径。

当 from 使用 glob 模式时，你应该显式定义 context。否则，插件会根据 from 的性质自动设置它：

• 如果 from 是文件，则 context 默认为文件所在的目录。结果路径将仅是文件名本身。

• 如果 from 是目录，则 context 设置为同一目录。结果路径将包含目录的内容（包括子目录），相对于它。

context 的使用在这些示例中进行了说明。

globOptions

[!警告]

onlyDirectories 不起作用，因为插件旨在复制文件，而不是单独复制目录。

类型

type globOptions = import("tinyglobby").GlobOptions;

默认值：undefined

允许你配置插件使用的 glob 模式匹配库。查看支持选项列表 要排除文件不被复制，请使用 globOptions.ignore 选项。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "public/**/*",
          globOptions: {
            dot: true,
            gitignore: true,
            ignore: ["**/file.*", "**/ignored-directory/**"],
          },
        },
      ],
    }),
  ],
};

filter

类型

type filter = (filepath: string) => boolean;

默认值：undefined

[!注意]

要按路径（例如，按扩展名或名称）忽略文件，请优先使用 [globOptions.ignore] 选项。

webpack.config.js

const fs = require("fs").promise;

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "public/**/*",
          filter: async (resourcePath) => {
            const data = await fs.promises.readFile(resourcePath);
            const content = data.toString();

            if (content === "my-custom-content") {
              return false;
            }

            return true;
          },
        },
      ],
    }),
  ],
};

toType

类型

type toType = "dir" | "file" | "template";

默认值：undefined

确定 to 选项的类型——它是目录、文件还是模板。有时很难判断 to 是什么，例如 path/to/dir-with.ext。如果你想将文件复制到目录中，你应该明确将类型设置为 dir。在大多数情况下，插件会自动确定正确的 type，因此你通常无需手动设置此选项。

'dir'

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "path/to/file.txt",
          to: "directory/with/extension.ext",
          toType: "dir",
        },
      ],
    }),
  ],
};

'file'

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "path/to/file.txt",
          to: "file/without/extension",
          toType: "file",
        },
      ],
    }),
  ],
};

'template'

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/",
          to: "dest/[name].[contenthash][ext]",
          toType: "template",
        },
      ],
    }),
  ],
};

force

类型

type force = boolean;

默认值：false

覆盖 compilation.assets 中已存在的文件（通常由其他插件或加载器添加）。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/**/*",
          to: "dest/",
          force: true,
        },
      ],
    }),
  ],
};

priority

类型

type priority = number;

默认值：0

允许指定具有相同目标名称的文件复制优先级。优先级较高的模式文件将稍后复制。要启用覆盖，必须将 force 选项设置为 true。webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        // Copied second and will overwrite "dir_2/file.txt"
        {
          from: "dir_1/file.txt",
          to: "newfile.txt",
          force: true,
          priority: 10,
        },
        // Copied first
        {
          from: "dir_2/file.txt",
          to: "newfile.txt",
          priority: 5,
        },
      ],
    }),
  ],
};

transform

类型

type transform =
  | {
      transformer: (input: string, absoluteFilename: string) => string | Buffer;
      cache?: boolean | TransformerCacheObject | undefined;
    }
  | ((input: string, absoluteFilename: string) => string | Buffer);

默认值：undefined

允许你在文件写入输出目录之前修改其内容。

function

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          // The `content` argument is a [`Buffer`](https://node.org.cn/api/buffer.html) object, it could be converted to a `String` to be processed using `content.toString()`
          // The `absoluteFrom` argument is a `String`, it is absolute path from where the file is being copied
          transform(content, absoluteFrom) {
            return optimize(content);
          },
        },
      ],
    }),
  ],
};

object

transformer

类型

type transformer = (input: string, absoluteFilename: string) => string;

默认值：undefined

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          // The `content` argument is a [`Buffer`](https://node.org.cn/api/buffer.html) object, it could be converted to a `String` to be processed using `content.toString()`
          // The `absoluteFrom` argument is a `String`, it is absolute path from where the file is being copied
          transform: {
            transformer(content, absoluteFrom) {
              return optimize(content);
            },
          },
        },
      ],
    }),
  ],
};

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          transform: {
            transformer(content, path) {
              return Promise.resolve(optimize(content));
            },
          },
        },
      ],
    }),
  ],
};

cache

类型

type cache =
  | boolean
  | {
      keys: {
        [key: string]: any;
      };
    }
  | {
      keys: (
        defaultCacheKeys: {
          [key: string]: any;
        },
        absoluteFilename: string,
      ) => Promise<{
        [key: string]: any;
      }>;
    }
  | undefined;

默认值：false

webpack.config.js

启用或禁用缓存并配置其行为。默认情况下，缓存目录位于：node_modules/.cache/copy-webpack-plugin。

boolean

启用/禁用 transform 缓存。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          transform: {
            transformer(content, path) {
              return optimize(content);
            },
            cache: true,
          },
        },
      ],
    }),
  ],
};

object

启用 transform 缓存并设置失效键。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          transform: {
            transformer(content, path) {
              return optimize(content);
            },
            cache: {
              keys: {
                // May be useful for invalidating cache based on external values
                // For example, you can invalid cache based on `process.version` - { node: process.version }
                key: "value",
              },
            },
          },
        },
      ],
    }),
  ],
};

你可以使用函数设置失效键。

简单函数

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          transform: {
            transformer(content, path) {
              return optimize(content);
            },
            cache: {
              keys: (defaultCacheKeys, absoluteFrom) => {
                const keys = getCustomCacheInvalidationKeysSync();

                return {
                  ...defaultCacheKeys,
                  keys,
                };
              },
            },
          },
        },
      ],
    }),
  ],
};

异步函数

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          transform: {
            transformer(content, path) {
              return optimize(content);
            },
            cache: {
              keys: async (defaultCacheKeys, absoluteFrom) => {
                const keys = await getCustomCacheInvalidationKeysAsync();

                return {
                  ...defaultCacheKeys,
                  keys,
                };
              },
            },
          },
        },
      ],
    }),
  ],
};

transformAll

类型

type transformAll = (
  data: {
    data: Buffer;
    sourceFilename: string;
    absoluteFilename: string;
  }[],
) => any;

默认值：undefined

允许你修改多个文件的内容并将合并结果保存到单个文件中。

[!注意]

必须指定 to 选项并指向文件。文件名中只允许使用 [contenthash] 和 [fullhash] 模板字符串。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/**/*.txt",
          to: "dest/file.txt",
          // The `assets` argument is an array of assets matched by the pattern `from` ("src/**/*.txt")
          transformAll(assets) {
            const result = assets.reduce((accumulator, asset) => {
              // The asset content can be obtained from `asset.source` using `source` method.
              // The asset content is a [`Buffer`](https://node.org.cn/api/buffer.html) object, it could be converted to a `String` to be processed using `content.toString()`
              const content = asset.data;

              accumulator = `${accumulator}${content}\n`;
              return accumulator;
            }, "");

            return result;
          },
        },
      ],
    }),
  ],
};

noErrorOnMissing

类型

type noErrorOnMissing = boolean;

默认值：false

如果文件缺失，则不生成错误。

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: path.resolve(__dirname, "missing-file.txt"),
          noErrorOnMissing: true,
        },
      ],
    }),
  ],
};

info

类型

type info =
  | Record<string, any>
  | ((item: {
      absoluteFilename: string;
      sourceFilename: string;
      filename: string;
      toType: ToType;
    }) => Record<string, any>);

默认值：undefined

允许添加资产信息。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        "relative/path/to/file.ext",
        {
          from: "**/*",
          // Terser skip this file for minification
          info: { minimized: true },
        },
      ],
    }),
  ],
};

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        "relative/path/to/file.ext",
        {
          from: "**/*",
          // Terser skip this file for minimization
          info: (file) => ({ minimized: true }),
        },
      ],
    }),
  ],
};

选项

• concurrency

concurrency

type

type concurrency = number;

默认值：100

限制对文件系统的同时请求数量。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [...patterns],
      options: { concurrency: 50 },
    }),
  ],
};

示例

from 的不同变体（glob、file 或 dir）。

考虑以下文件结构：

src/directory-nested/deep-nested/deepnested-file.txt
src/directory-nested/nested-file.txt

From 是 Glob

你用 from 指定的所有内容都将包含在结果中。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/directory-nested/**/*",
        },
      ],
    }),
  ],
};

结果

src/directory-nested/deep-nested/deepnested-file.txt,
src/directory-nested/nested-file.txt

如果你不希望结果路径以 src/directory-nested/ 开头，则应将 src/directory-nested/ 移动到 context，以便 from 中只保留 glob 模式 **/*。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "**/*",
          context: path.resolve(__dirname, "src", "directory-nested"),
        },
      ],
    }),
  ],
};

结果

deep-nested/deepnested-file.txt,
nested-file.txt

From 是 Dir

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: path.resolve(__dirname, "src", "directory-nested"),
        },
      ],
    }),
  ],
};

结果

deep-nested/deepnested-file.txt,
nested-file.txt

从技术上讲，这等同于使用 **/* 并将预定义上下文设置为指定目录。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "**/*",
          context: path.resolve(__dirname, "src", "directory-nested"),
        },
      ],
    }),
  ],
};

结果

deep-nested/deepnested-file.txt,
nested-file.txt

From 是 File

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: path.resolve(
            __dirname,
            "src",
            "directory-nested",
            "nested-file.txt",
          ),
        },
      ],
    }),
  ],
};

结果

nested-file.txt

从技术上讲，这是一个文件名，其预定义上下文等于文件所在的目录 path.dirname(pathToFile)。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "nested-file.txt",
          context: path.resolve(__dirname, "src", "directory-nested"),
        },
      ],
    }),
  ],
};

结果

nested-file.txt

忽略文件

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: path.posix.join(
            path.resolve(__dirname, "src").replace(/\\/g, "/"),
            "**/*",
          ),
          globOptions: {
            ignore: [
              // Ignore all `txt` files
              "**/*.txt",
              // Ignore all files in all subdirectories
              "**/subdir/**",
            ],
          },
        },
      ],
    }),
  ],
};

扁平复制

移除所有目录引用并仅复制文件名。

[!警告]

如果文件具有相同的名称，则结果是不确定的。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/**/*",
          to: "[name][ext]",
        },
      ],
    }),
  ],
};

结果

file-1.txt
file-2.txt
nested-file.txt

复制到新目录

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          // When copying files starting with a dot, must specify the toType option
          // toType: "file",
          to({ context, absoluteFilename }) {
            return `newdirectory/${path.relative(context, absoluteFilename)}`;
          },
          from: "directory",
        },
      ],
    }),
  ],
};

结果

"newdirectory/file-1.txt",
"newdirectory/nestedfile.txt",
"newdirectory/nested/deep-nested/deepnested.txt",
"newdirectory/nested/nestedfile.txt",

跳过通过压缩器运行 JavaScript 文件

如果你需要简单地将 *.js 文件“原样”复制到目标位置，而无需使用 Terser 对它们进行评估和压缩，这将非常有用。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        "relative/path/to/file.ext",
        {
          from: "**/*",
          // Terser skip this file for minimization
          info: { minimized: true },
        },
      ],
    }),
  ],
};

yarn workspaces 和 monorepos

当使用 yarn workspaces 或 monorepos 时，由于包提升的方式，从 node_modules 的相对复制路径可能会损坏。为了避免这种情况，你应该通过使用 require.resolve 明确指定从何处复制文件。

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: `${path.dirname(
            require.resolve(`${moduleName}/package.json`),
          )}/target`,
          to: "target",
        },
      ],
    }),
  ],
};

贡献

我们欢迎所有贡献！

如果你是新用户，请在提交问题或拉取请求之前花一些时间阅读我们的贡献指南。

CONTRIBUTING

许可证

MIT

CssMinimizerWebpackPlugin

此插件使用 cssnano 来优化和压缩你的 CSS。

它作为 optimize-css-assets-webpack-plugin 的更精确替代方案，对源映射、带查询字符串的资产、缓存和并行处理有更好的支持。

入门

首先，你需要安装 css-minimizer-webpack-plugin

npm install css-minimizer-webpack-plugin --save-dev

或

yarn add -D css-minimizer-webpack-plugin

或

pnpm add -D css-minimizer-webpack-plugin

然后将插件添加到你的 webpack 配置中。例如：

webpack.config.js

const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");

module.exports = {
  module: {
    rules: [
      {
        test: /\.s?css$/,
        use: [MiniCssExtractPlugin.loader, "css-loader", "sass-loader"],
      },
    ],
  },
  optimization: {
    minimizer: [
      // For webpack v5, you can use the `...` syntax to extend existing minimizers (i.e. `terser-webpack-plugin`), uncomment the next line // `...`,
      new CssMinimizerPlugin(),
    ],
  },
  plugins: [new MiniCssExtractPlugin()],
};

[!注意]

默认情况下，这只在生产模式下启用 CSS 优化。

要在开发模式下也启用它，请将 optimization.minimize 选项设置为 true。

webpack.config.js

// [...]
module.exports = {
  optimization: {
    // [...]
    minimize: true,
  },
};

最后，使用你偏好的方法运行 Webpack。

关于源映射的注意事项

此插件仅适用于 devtool 选项的 source-map、inline-source-map、hidden-source-map 和 nosources-source-map 值。

为什么？因为 CSS 仅支持这些源映射类型。

该插件尊重 devtool 设置并内部使用 SourceMapDevToolPlugin。

使用受支持的 devtool 值可启用源映射生成。

在 SourceMapDevToolPlugin 中启用 columns 选项也允许生成源映射。

使用源映射将错误消息位置映射到其原始模块（请注意，这可能会减慢编译速度）。

如果你使用自己的 minify 函数，请参阅 minify 部分以正确处理源映射。

选项

test

• 类型：String|RegExp|Array<String|RegExp>
• 默认值：/\.css(\?.*)?$/i

用于匹配文件的测试。

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        test: /\.foo\.css$/i,
      }),
    ],
  },
};

include

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

要包含的文件。

webpack.config.js

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        include: /\/includes/,
      }),
    ],
  },
};

exclude

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

要排除的文件。

webpack.config.js

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        exclude: /\/excludes/,
      }),
    ],
  },
};

parallel

• 类型：Boolean|Number
• 默认值：true

使用多进程并行运行以提高构建速度。

默认并发运行数量：os.cpus().length - 1 或 os.availableParallelism() - 1（如果此函数受支持）。

ℹ️ 并行化可以显著加快你的构建速度，因此强烈推荐。如果启用了并行化，minimizerOptions 中的包必须通过字符串（packageName 或 require.resolve(packageName)）引入。在minimizerOptions中阅读更多内容。

Boolean

启用或禁用多进程并行运行。

webpack.config.js

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        parallel: true,
      }),
    ],
  },
};

Number

启用多进程并行运行并指定并发运行的数量。

webpack.config.js

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        parallel: 4,
      }),
    ],
  },
};

minify

• 类型：Function|Array<Function>
• 默认值：CssMinimizerPlugin.cssnanoMinify

覆盖默认的压缩函数。

默认情况下，插件使用 cssnano 包。

这在测试或使用未发布版本或分支时很有用。

可选选项：

• CssMinimizerPlugin.cssnanoMinify
• CssMinimizerPlugin.cssoMinify
• CssMinimizerPlugin.cleanCssMinify
• CssMinimizerPlugin.esbuildMinify
• CssMinimizerPlugin.lightningCssMinify（以前是CssMinimizerPlugin.parcelCssMinify，包已重命名，但我们为了向后兼容保留它）
• async (data, inputMap, minimizerOptions) => {return {code: "a{color: red}", map: "...", warnings: [], errors: []}}

[!警告]

当启用了 parallel 选项时，总是在 minify 函数内部使用 require。.

Function

webpack.config.js

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: {
          level: {
            1: {
              roundingPrecision: "all=3,px=5",
            },
          },
        },
        minify: CssMinimizerPlugin.cleanCssMinify,
      }),
    ],
  },
};

Array

如果一个函数数组传递给 minify 选项，则 minimizerOptions 也必须是一个数组。

minify 数组中的函数索引对应于 minimizerOptions 数组中具有相同索引的选项对象。

webpack.config.js

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: [
          {}, // Options for the first function (CssMinimizerPlugin.cssnanoMinify)
          {}, // Options for the second function (CssMinimizerPlugin.cleanCssMinify)
          {}, // Options for the third function
        ],
        minify: [
          CssMinimizerPlugin.cssnanoMinify,
          CssMinimizerPlugin.cleanCssMinify,
          async (data, inputMap, minimizerOptions) => {
            //  Custom minifier function
            return {
              code: `a{color: red}`,
              map: `{"version": "3", ...}`,
              warnings: [],
              errors: [],
            };
          },
        ],
      }),
    ],
  },
};

minimizerOptions

• 类型：Object|Array<Object>
• 默认值：{ preset: 'default' }

Cssnano 优化选项。

Object

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: {
          preset: [
            "default",
            {
              discardComments: { removeAll: true },
            },
          ],
        },
      }),
    ],
  },
};

Array

minify 数组中的函数索引对应于 minimizerOptions 数组中具有相同索引的选项对象。

如果你将 minimizerOptions 作为对象使用，所有 minify 函数都将接受它。

如果启用了并行化，minimizerOptions 中的包必须通过字符串（packageName 或 require.resolve(packageName)）引用。在这种情况下，我们不应该使用 require/import。

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: {
          preset: require.resolve("cssnano-preset-simple"),
        },
      }),
    ],
  },
};

processorOptions (⚠ 仅限 cssnano)

• 类型：Object
• 默认值：{ from: assetName }

允许过滤 cssnano 的 processoptions 选项。

parser、stringifier 和 syntax 可以是函数或指示将被导入的模块的字符串。

[!警告]

如果这些选项中的任何一个作为函数传递，则必须禁用 parallel 选项。.

import sugarss from "sugarss";

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        parallel: false,
        minimizerOptions: {
          processorOptions: {
            parser: sugarss,
          },
        },
      }),
    ],
  },
};

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: {
          processorOptions: {
            parser: "sugarss",
          },
        },
      }),
    ],
  },
};

warningsFilter

• 类型：Function<(warning, file, source) -> Boolean>
• 默认值：() => true

过滤 css-minimizer 警告（默认情况下为 cssnano）。

返回 true 以保留警告，或返回一个 falsy 值（false/null/undefined）以抑制它。

[!警告]

除非启用了源映射，否则 source 参数将为 undefined。

webpack.config.js

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        warningsFilter: (warning, file, source) => {
          if (/Dropping unreachable code/i.test(warning)) {
            return true;
          }

          if (/file\.css/i.test(file)) {
            return true;
          }

          if (/source\.css/i.test(source)) {
            return true;
          }

          return false;
        },
      }),
    ],
  },
};

示例

使用源映射

不要忘记为所有加载器启用 sourceMap 选项。

const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");

module.exports = {
  devtool: "source-map",
  module: {
    rules: [
      {
        test: /\.s?css$/,
        use: [
          MiniCssExtractPlugin.loader,
          { loader: "css-loader", options: { sourceMap: true } },
          { loader: "sass-loader", options: { sourceMap: true } },
        ],
      },
    ],
  },
  optimization: {
    minimizer: [new CssMinimizerPlugin()],
  },
  plugins: [new MiniCssExtractPlugin()],
};

删除所有注释

删除所有注释，包括以 /*! 开头的注释。

module.exports = {
  optimization: {
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: {
          preset: [
            "default",
            {
              discardComments: { removeAll: true },
            },
          ],
        },
      }),
    ],
  },
};

使用自定义压缩器 csso

webpack.config.js

module.exports = {
  // Uncomment if you need source maps
  // devtool: "source-map",
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minify: CssMinimizerPlugin.cssoMinify,
        // Uncomment this line for options
        // minimizerOptions: { restructure: false },
      }),
    ],
  },
};

使用自定义压缩器 clean-css

webpack.config.js

module.exports = {
  // Uncomment if you need source maps
  // devtool: "source-map",
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minify: CssMinimizerPlugin.cleanCssMinify,
        // Uncomment this line for options
        // minimizerOptions: { compatibility: 'ie11,-properties.merging' },
      }),
    ],
  },
};

使用自定义压缩器 esbuild

webpack.config.js

module.exports = {
  // Uncomment if you need source maps
  // devtool: "source-map",
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minify: CssMinimizerPlugin.esbuildMinify,
      }),
    ],
  },
};

使用自定义压缩器 lightningcss，以前是 @parcel/css

webpack.config.js

module.exports = {
  // devtool: "source-map", // Uncomment for source maps
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minify: CssMinimizerPlugin.lightningCssMinify,
        // Uncomment this line for options
        // minimizerOptions: { targets: { ie: 11 }, drafts: { nesting: true } },
      }),
    ],
  },
};

使用自定义压缩器 swc

webpack.config.js

module.exports = {
  // devtool: "source-map", // Uncomment for source maps
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minify: CssMinimizerPlugin.swcMinify,
        // Uncomment this line for options
        // minimizerOptions: {},
      }),
    ],
  },
};

贡献

我们欢迎所有贡献！

如果你是新用户，请花一些时间阅读我们的贡献指南。

CONTRIBUTING

许可证

MIT

DefinePlugin

DefinePlugin 在**编译**时将代码中的变量替换为其他值或表达式。这对于在开发构建和生产构建之间实现不同行为非常有用。如果你在开发构建中进行日志记录，但在生产构建中不进行，则可以使用全局常量来确定是否进行日志记录。这正是 DefinePlugin 的用武之地，它为开发和生产构建设置了“一劳永逸”的规则。

new webpack.DefinePlugin({
  // Definitions...
});

用法

传递给 DefinePlugin 的每个键都是一个标识符或多个用 . 连接的标识符。

• 如果值是字符串，它将用作代码片段。
• 如果值不是字符串，它将被字符串化（包括函数）。
• 如果值是对象，所有键的定义方式都相同。
• 如果你在键前加上 typeof，则它仅在 typeof 调用中定义。

这些值将内联到代码中，从而允许通过压缩来移除冗余的条件判断。

new webpack.DefinePlugin({
  PRODUCTION: JSON.stringify(true),
  VERSION: JSON.stringify('5fa3b9'),
  BROWSER_SUPPORTS_HTML5: true,
  TWO: '1+1',
  'typeof window': JSON.stringify('object'),
  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
});

console.log('Running App version ' + VERSION);
if (!BROWSER_SUPPORTS_HTML5) require('html5shiv');

if (!PRODUCTION) {
  console.log('Debug info');
}

if (PRODUCTION) {
  console.log('Production log');
}

未经压缩的 webpack 处理后结果为：

if (!true) {
  console.log('Debug info');
}
if (true) {
  console.log('Production log');
}

然后在压缩后结果为：

console.log('Production log');

功能标志

使用功能标志在生产/开发构建中启用/禁用功能。

new webpack.DefinePlugin({
  NICE_FEATURE: JSON.stringify(true),
  EXPERIMENTAL_FEATURE: JSON.stringify(false),
});

服务 URL

在生产/开发构建中使用不同的服务 URL

new webpack.DefinePlugin({
  SERVICE_URL: JSON.stringify('https://dev.example.com'),
});

通过 runtimeValue 获取运行时值

function (getterFunction, [string] | true | object) => getterFunction()

可以定义变量，其值依赖于文件，并且当这些文件在文件系统中更改时会重新评估。这意味着当这些被监视的文件更改时，webpack 将重新构建。

webpack.DefinePlugin.runtimeValue 函数有两个参数：

• 第一个参数是一个 function(module, key, version)，它应该返回要分配给定义的值。

• 第二个参数可以是要监视的文件路径数组，也可以是 true 来标记模块不可缓存。从 5.26.0 开始，它还可以接受一个带有以下属性的对象参数：

  • fileDependencies?: string[] 函数所依赖的文件列表。
  • contextDependencies?: string[] 函数所依赖的目录列表。
  • missingDependencies?: string[] 函数所依赖的不存在的文件列表。
  • buildDependencies?: string[] 函数所依赖的构建依赖项列表。
  • version?: string | () => string 函数的版本。

const fileDep = path.resolve(__dirname, 'sample.txt');

new webpack.DefinePlugin({
  BUILT_AT: webpack.DefinePlugin.runtimeValue(Date.now, {
    fileDependencies: [fileDep],
  }),
});

BUILT_AT 的值将是 'sample.txt' 在文件系统中最后更新的时间，例如 1597953013291。

DllPlugin

DllPlugin 和 DllReferencePlugin 提供了拆分 bundles 的方法，可以显著提高构建时间性能。“DLL”一词代表动态链接库，最初由微软引入。

DllPlugin

此插件在单独的 webpack 配置中专门用于创建 dll-only-bundle。它创建一个 manifest.json 文件，该文件由 DllReferencePlugin 用于映射依赖项。

• context (可选)：manifest 文件中请求的 context（默认为 webpack context）。
• format (boolean = false)：如果为 true，则 manifest json 文件（输出）将被格式化。
• name：公开的 dll 函数的名称（模板路径：[fullhash], [chunkhash], [contenthash], & [name]）
• path：manifest json 文件（输出）的绝对路径。
• entryOnly (boolean = true)：如果为 true，则只公开入口点。
• type：dll bundle 的类型。

new webpack.DllPlugin(options);

创建一个 manifest.json 文件，并写入给定 path。它包含从 require 和 import 请求到模块 ID 的映射。它由 DllReferencePlugin 使用。

将此插件与 output.library 选项结合使用，以公开（即，放入全局作用域）dll 函数。

DllReferencePlugin

此插件用于主要的 webpack 配置中，它引用 dll-only-bundle(s) 以按需引入预构建的依赖项。

• context：（绝对路径）manifest（或 content 属性）中请求的 context。
• extensions：用于解析 dll bundle 中模块的扩展名（仅在使用 'scope' 时使用）。
• manifest：一个包含 content 和 name 的对象，或者一个指向编译时加载的 JSON manifest 绝对路径的字符串。
• content (可选)：从请求到模块 ID 的映射（默认为 manifest.content）。
• name (可选)：dll 公开的标识符（默认为 manifest.name）（另请参阅 externals）。
• scope (可选)：用于访问 dll 内容的前缀。
• sourceType (可选)：dll 的公开方式（libraryTarget）。

new webpack.DllReferencePlugin(options);

引用 dll manifest 文件，将依赖名称映射到模块 ID，然后根据需要使用内部 __webpack_require__ 函数引入它们。

模式

此插件可用于两种不同的模式：作用域模式和映射模式。

作用域模式

dll 的内容可在模块前缀下访问。即，当 scope = 'xyz' 时，dll 中的文件 abc 可通过 require('xyz/abc') 访问。

映射模式

dll 的内容被映射到当前目录。如果所需的 file 与 dll 中的文件匹配（解析后），则使用 dll 中的文件代替。

由于这发生在解析 dll bundle 中的每个文件之后，因此 dll bundle 的消费者必须可以使用相同的路径。即，如果 dll 包含 lodash 和文件 abc，则 require('lodash') 和 require('./abc') 将从 dll 中使用，而不是将它们构建到主 bundle 中。

用法

webpack.vendor.config.js

const path = require('path');

new webpack.DllPlugin({
  context: __dirname,
  name: '[name]_[fullhash]',
  path: path.join(__dirname, 'manifest.json'),
});

webpack.app.config.js

new webpack.DllReferencePlugin({
  context: __dirname,
  manifest: require('./manifest.json'),
  scope: 'xyz',
  sourceType: 'commonjs2',
});

示例

供应商 和 用户

两个独立的示例文件夹。演示了作用域和上下文。

参考

来源

• DllPlugin 源码
• DllReferencePlugin 源码
• DllEntryPlugin 源码
• DllModuleFactory 源码
• ManifestPlugin 源码

测试

• DllPlugin 创建测试
• DllPlugin 无作用域测试
• DllReferencePlugin 使用 Dll 测试

EnvironmentPlugin

EnvironmentPlugin 是在 process.env 键上使用 DefinePlugin 的简写形式。

用法

EnvironmentPlugin 接受键数组或将其键映射到其默认值的对象。

new webpack.EnvironmentPlugin(['NODE_ENV', 'DEBUG']);

这等同于以下 DefinePlugin 应用：

new webpack.DefinePlugin({
  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
  'process.env.DEBUG': JSON.stringify(process.env.DEBUG),
});

使用默认值

或者，EnvironmentPlugin 支持一个对象，该对象将键映射到其默认值。如果 process.env 中未定义键，则取键的默认值。

new webpack.EnvironmentPlugin({
  NODE_ENV: 'development', // use 'development' unless process.env.NODE_ENV is defined
  DEBUG: false,
});

示例

让我们研究在测试文件 entry.js 上运行先前的 EnvironmentPlugin 配置时的结果：

if (process.env.NODE_ENV === 'production') {
  console.log('Welcome to production');
}
if (process.env.DEBUG) {
  console.log('Debugging output');
}

当在终端中执行 NODE_ENV=production webpack 进行构建时，entry.js 变为：

if ('production' === 'production') {
  // <-- 'production' from NODE_ENV is taken
  console.log('Welcome to production');
}
if (false) {
  // <-- default value is taken
  console.log('Debugging output');
}

运行 DEBUG=false webpack 得到：

if ('development' === 'production') {
  // <-- default value is taken
  console.log('Welcome to production');
}
if ('false') {
  // <-- 'false' from DEBUG is taken
  console.log('Debugging output');
}

用例：Git 版本

以下 EnvironmentPlugin 配置提供了 process.env.GIT_VERSION（例如“v5.4.0-2-g25139f57f”）和 process.env.GIT_AUTHOR_DATE（例如“2020-11-04T12:25:16+01:00”），对应于仓库的最后一次 Git 提交：

const child_process = require('child_process');
function git(command) {
  return child_process.execSync(`git ${command}`, { encoding: 'utf8' }).trim();
}

new webpack.EnvironmentPlugin({
  GIT_VERSION: git('describe --always'),
  GIT_AUTHOR_DATE: git('log -1 --format=%aI'),
});

DotenvPlugin

第三方 DotenvPlugin (dotenv-webpack) 允许你公开（一部分）dotenv 变量

// .env
DB_HOST=127.0.0.1
DB_PASS=foobar
S3_API=mysecretkey

new Dotenv({
  path: './.env', // Path to .env file (this is the default)
  safe: true, // load .env.example (defaults to "false" which does not use dotenv-safe)
});

EslintWebpackPlugin

此版本的 eslint-webpack-plugin 仅支持 webpack 5。对于 webpack 4，请参阅 2.x 分支。

此插件使用 ESLint 在 Webpack 构建过程中查找并修复你的 JavaScript 代码问题。

入门

首先，你需要安装 eslint-webpack-plugin

npm install eslint-webpack-plugin --save-dev

或

yarn add -D eslint-webpack-plugin

或

pnpm add -D eslint-webpack-plugin

[!注意]

如果你还没有安装，还需要从 npm 安装 eslint >= 8

npm install eslint --save-dev

或

yarn add -D eslint

或

pnpm add -D eslint

然后将插件添加到您的 webpack 配置中。例如

const ESLintPlugin = require('eslint-webpack-plugin');

module.exports = {
  // ...
  plugins: [new ESLintPlugin(options)],
  // ...
};

选项

你可以传递 ESLint Node.js API 选项。

[!注意]

你提供的配置选项将传递给 ESLint 类。这与你在 package.json 或 eslint.config.js（从 ESLint v9.0.0 开始，以前是 .eslintrc）中指定的选项集不同。有关详细信息，请参阅 ESLint 文档。

[!警告]

在 eslint-webpack-plugin 版本 1 中，选项被传递给了现在已废弃的 CLIEngine。

cache

• 类型

type cache = boolean;

• 默认值：true

缓存默认启用以减少执行时间。

cacheLocation

• 类型

type cacheLocation = string;

• 默认值：node_modules/.cache/eslint-webpack-plugin/.eslintcache

指定缓存位置的路径。可以是文件或目录。

configType

• 类型

type configType = 'flat' | 'eslintrc';

• 默认值：flat

指定 ESLint 使用的配置类型。

• eslintrc 是大多数 ESLint 版本中可用的经典配置格式。
• flat 是 ESLint 8.21.0 中引入的新格式。

新的配置格式在其自己的文档中进行了解释。

context

• 类型

type context = string;

• 默认值：compiler.context

linting 的基本目录。

eslintPath

• 类型

type eslintPath = string;

• 默认值：eslint

用于 linting 的 eslint 实例路径。

如果 eslintPath 是像官方 ESLint 一样的文件夹，或者指定了 formatter 选项，那么现在您无需安装 eslint。

extensions

• 类型

type extensions = string | Array<string>;

• 默认值：'js'