MiniCssExtractPlugin

免责声明: MiniCssExtractPlugin 是由社区成员维护的第三方包,它可能没有与 webpack 相同的支持、安全策略或许可证,并且它不是由 webpack 维护的。

npm node tests coverage discussion size

此插件将 CSS 提取到单独的文件中。它为每个包含 CSS 的 JS 文件创建一个 CSS 文件。它支持按需加载 CSS 和 SourceMaps。

它建立在 webpack v5 新功能之上,需要 webpack 5 才能工作。

与 extract-text-webpack-plugin 相比

  • 异步加载
  • 无重复编译(性能)
  • 更易于使用
  • 特定于 CSS

入门

首先,你需要安装 mini-css-extract-plugin

npm install --save-dev mini-css-extract-plugin

yarn add -D mini-css-extract-plugin

pnpm add -D mini-css-extract-plugin

建议将 mini-css-extract-plugincss-loader 结合使用

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

style.css

body {
  background: green;
}

component.js

import "./style.css";

webpack.config.js

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

module.exports = {
  plugins: [new MiniCssExtractPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};

警告

请注意,如果你从 webpack 入口点导入 CSS 或在 初始 块中导入样式,mini-css-extract-plugin 将不会将此 CSS 加载到页面中。请使用 html-webpack-plugin 自动生成 link 标记或使用 link 标记创建 index.html 文件。

警告

源映射仅适用于 source-map/nosources-source-map/hidden-nosources-source-map/hidden-source-map 值,因为 CSS 仅支持带有 sourceMappingURL 注释的源映射(即 //# sourceMappingURL=style.css.map)。如果你需要将 devtool 设置为其他值,则可以使用 sourceMap: truecss-loader 启用提取 CSS 的源映射生成。

选项

插件选项

filename

类型

type filename =
  | string
  | ((pathData: PathData, assetInfo?: AssetInfo) => string);

默认值:[name].css

此选项决定了每个输出 CSS 文件的名称。

类似于 output.filename

chunkFilename

类型

type chunkFilename =
  | string
  | ((pathData: PathData, assetInfo?: AssetInfo) => string);

默认值:基于 filename

仅在 webpack@5 中可以将 chunkFilename 指定为 function

此选项决定了非入口块文件的文件名。

类似于 output.chunkFilename

ignoreOrder

类型

type ignoreOrder = boolean;

默认值:false

移除顺序警告。有关详细信息,请参阅下面的 示例

insert

类型

type insert = string | ((linkTag: HTMLLinkElement) => void);

默认值:document.head.appendChild(linkTag);

非初始(异步) CSS 块在指定位置插入 link 标签

警告

仅适用于 非初始(异步) 块。

默认情况下,mini-css-extract-plugin 将样式(<link> 元素)追加到当前 windowdocument.head

但在某些情况下,可能需要对追加目标进行更精细的控制,甚至延迟 link 元素的插入。例如,当为在 iframe 内运行的应用程序异步加载样式时,会出现这种情况。在这种情况下,可以将 insert 配置为函数或自定义选择器。

如果你要针对一个 iframe,确保父文档有足够的访问权限来进入框架文档并向其追加元素。

string

允许设置自定义 查询选择器。一个新的 <link> 元素将在找到的项目后插入。

webpack.config.js

new MiniCssExtractPlugin({
  insert: "#some-element",
});

一个新的 <link> 元素将在 id 为 some-element 的元素后插入。

function

允许覆盖默认行为并在任何位置插入样式。

⚠ 请不要忘记,此代码将与你的应用程序一起在浏览器中运行。由于并非所有浏览器都支持最新的 ECMA 特性,如 letconst箭头函数表达式 等,我们建议你仅使用 ECMA 5 特性和语法。

insert 函数被序列化为字符串并传递给插件。这意味着它无法访问 webpack 配置模块的范围。

webpack.config.js

new MiniCssExtractPlugin({
  insert: function (linkTag) {
    var reference = document.querySelector("#some-element");
    if (reference) {
      reference.parentNode.insertBefore(linkTag, reference);
    }
  },
});

一个新的 <link> 元素将在 id 为 some-element 的元素前插入。

attributes

类型

type attributes = Record<string, string>};

默认值:{}

警告

仅适用于 非初始(异步) 块。

如果已定义,mini-css-extract-plugin 将在 <link> 元素上附加给定属性及其值。

webpack.config.js

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

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      attributes: {
        id: "target",
        "data-target": "example",
      },
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};

注意

它仅适用于动态加载的 css 块,如果你想修改 html 文件中的链接属性,请使用 html-webpack-plugin

linkType

类型

type linkType = string | boolean;

默认值:text/css

此选项允许使用自定义链接类型加载异步块,例如 <link type="text/css" ...>

string

可能的值:text/css

webpack.config.js

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

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      linkType: "text/css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};
boolean

false 禁用链接 type 属性

webpack.config.js

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

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      linkType: false,
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};

runtime

类型

type runtime = boolean;

默认值:true

允许启用/禁用运行时生成。CSS 仍将被提取,并可用于自定义加载方法。例如,你可以使用 assets-webpack-plugin 检索它们,然后使用你自己的运行时代码在需要时下载资产。

false 跳过。

webpack.config.js

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

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      runtime: false,
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};

experimentalUseImportModule

类型

type experimentalUseImportModule = boolean;

默认值:undefined

如果未显式启用,则默认启用(即 truefalse 允许你显式控制此选项),并且新 API 可用(至少需要 webpack 5.52.0)。布尔值自版本 5.33.2 起可用,但你需要启用 experiments.executeModule(从 webpack 5.52.0 起不再需要)。

使用新的 webpack API 来执行模块,而不是子编译器。这极大地提高了性能和内存使用率。

当与 experiments.layers 结合使用时,这会向加载器选项添加一个 layer 选项,以指定 css 执行的层。

webpack.config.js

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

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      // You don't need this for `>= 5.52.0` due to the fact that this is enabled by default
      // Required only for `>= 5.33.2 & <= 5.52.0`
      // Not available/unsafe for `<= 5.33.2`
      experimentalUseImportModule: true,
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};

加载器选项

publicPath

类型

type publicPath =
  | string
  | ((resourcePath: string, rootContext: string) => string);

默认值:webpackOptions.output 中的 publicPath

CSS 中的图像、文件等外部资源指定自定义公共路径。与 output.publicPath 的工作方式相同

string

webpack.config.js

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

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      // Options similar to the same options in webpackOptions.output
      // both options are optional
      filename: "[name].css",
      chunkFilename: "[id].css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {
              publicPath: "/public/path/to/",
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};
function

webpack.config.js

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

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      // Options similar to the same options in webpackOptions.output
      // both options are optional
      filename: "[name].css",
      chunkFilename: "[id].css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {
              publicPath: (resourcePath, context) => {
                return path.relative(path.dirname(resourcePath), context) + "/";
              },
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

emit

类型

type emit = boolean;

默认值:true

如果为 true,则会发出一个文件(将文件写入文件系统)。如果为 false,则插件将提取 CSS,但不会发出文件。对于服务端软件包,禁用此选项通常很有用。

esModule

类型

type esModule = boolean;

默认值:true

默认情况下,mini-css-extract-plugin 会生成使用 ES 模块语法的 JS 模块。在某些情况下,使用 ES 模块是有益的,例如在 模块串联tree shaking 的情况下。

你可以使用以下方式启用 CommonJS 语法

webpack.config.js

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

module.exports = {
  plugins: [new MiniCssExtractPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {
              esModule: false,
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

示例

推荐

对于 production 构建,建议从你的 bundle 中提取 CSS,以便以后能够并行加载 CSS/JS 资源。这可以通过使用 mini-css-extract-plugin 来实现,因为它创建了单独的 css 文件。对于 development 模式(包括 webpack-dev-server),你可以使用 style-loader,因为它使用多个 并且运行得更快。

不要同时使用 style-loadermini-css-extract-plugin

webpack.config.js

const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const devMode = process.env.NODE_ENV !== "production";

module.exports = {
  module: {
    rules: [
      {
        // If you enable `experiments.css` or `experiments.futureDefaults`, please uncomment line below
        // type: "javascript/auto",
        test: /\.(sa|sc|c)ss$/,
        use: [
          devMode ? "style-loader" : MiniCssExtractPlugin.loader,
          "css-loader",
          "postcss-loader",
          "sass-loader",
        ],
      },
    ],
  },
  plugins: [].concat(devMode ? [] : [new MiniCssExtractPlugin()]),
};

最小示例

webpack.config.js

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

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      // Options similar to the same options in webpackOptions.output
      // all options are optional
      filename: "[name].css",
      chunkFilename: "[id].css",
      ignoreOrder: false, // Enable to remove warnings about conflicting order
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {
              // you can specify a publicPath here
              // by default it uses publicPath in webpackOptions.output
              publicPath: "../",
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

CSS 模块的命名导出

⚠ 本地变量的名称已转换为 camelCase

⚠ 不允许在 css 类名中使用 JavaScript 保留字。

css-loader 中的选项 esModulemodules.namedExport 应启用。

styles.css

.foo-baz {
  color: red;
}
.bar {
  color: blue;
}

index.js

import { fooBaz, bar } from "./styles.css";

console.log(fooBaz, bar);

你可以使用以下方式启用 ES 模块命名导出

webpack.config.js

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

module.exports = {
  plugins: [new MiniCssExtractPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
          },
          {
            loader: "css-loader",
            options: {
              esModule: true,
              modules: {
                namedExport: true,
                localIdentName: "foo__[name]__[local]",
              },
            },
          },
        ],
      },
    ],
  },
};

publicPath 选项作为函数

webpack.config.js

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

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      // Options similar to the same options in webpackOptions.output
      // both options are optional
      filename: "[name].css",
      chunkFilename: "[id].css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {
              publicPath: (resourcePath, context) => {
                // publicPath is the relative path of the resource to the context
                // e.g. for ./css/admin/main.css the publicPath will be ../../
                // while for ./css/main.css the publicPath will be ../
                return path.relative(path.dirname(resourcePath), context) + "/";
              },
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

高级配置示例

此插件不应与加载器链中的 style-loader 一起使用。

以下是一个示例,它在 development 中同时具有 HMR,并在 production 构建中将你的样式提取到一个文件中。

(为清楚起见,省略了加载器选项,根据你的需要进行相应调整。)

如果你正在使用 webpack-dev-server,则不应使用 HotModuleReplacementPlugin 插件。webpack-dev-server 使用 hot 选项启用/禁用 HMR。

webpack.config.js

const webpack = require("webpack");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const devMode = process.env.NODE_ENV !== "production";

const plugins = [
  new MiniCssExtractPlugin({
    // Options similar to the same options in webpackOptions.output
    // both options are optional
    filename: devMode ? "[name].css" : "[name].[contenthash].css",
    chunkFilename: devMode ? "[id].css" : "[id].[contenthash].css",
  }),
];
if (devMode) {
  // only enable hot in development
  plugins.push(new webpack.HotModuleReplacementPlugin());
}

module.exports = {
  plugins,
  module: {
    rules: [
      {
        test: /\.(sa|sc|c)ss$/,
        use: [
          MiniCssExtractPlugin.loader,
          "css-loader",
          "postcss-loader",
          "sass-loader",
        ],
      },
    ],
  },
};

热模块重新加载 (HMR)

注意

HMR 在 webpack 5 中自动支持。无需配置它。跳过以下内容

mini-css-extract-plugin 支持在开发中对实际 css 文件进行热重新加载。提供了一些选项来启用标准样式表和本地作用域 CSS 或 CSS 模块的 HMR。以下是 mini-css 的示例配置,用于与 CSS 模块一起使用 HMR。

如果你正在使用 webpack-dev-server,则不应使用 HotModuleReplacementPlugin 插件。webpack-dev-server 使用 hot 选项启用/禁用 HMR。

webpack.config.js

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

const plugins = [
  new MiniCssExtractPlugin({
    // Options similar to the same options in webpackOptions.output
    // both options are optional
    filename: devMode ? "[name].css" : "[name].[contenthash].css",
    chunkFilename: devMode ? "[id].css" : "[id].[contenthash].css",
  }),
];
if (devMode) {
  // only enable hot in development
  plugins.push(new webpack.HotModuleReplacementPlugin());
}

module.exports = {
  plugins,
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {},
          },
          "css-loader",
        ],
      },
    ],
  },
};

最小化以进行生产

要缩小输出,请使用 css-minimizer-webpack-plugin 等插件。

webpack.config.js

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

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

这将仅在生产模式下启用 CSS 优化。如果你希望在开发中也运行它,请将 optimization.minimize 选项设置为 true。

使用预加载或内联 CSS

运行时代码通过 <link><style> 标记检测已添加的 CSS。这在服务器端注入 CSS 以进行服务器端渲染时非常有用。<link> 标记的 href 必须与用于加载 CSS 块的 URL 匹配。data-href 属性也可用于 <link><style>。内联 CSS 时,必须使用 data-href

将所有 CSS 提取到一个文件中

可以使用 optimization.splitChunks.cacheGroups 将 CSS 提取到一个 CSS 文件中。

webpack.config.js

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

module.exports = {
  optimization: {
    splitChunks: {
      cacheGroups: {
        styles: {
          name: "styles",
          type: "css/mini-extract",
          chunks: "all",
          enforce: true,
        },
      },
    },
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: "[name].css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};

请注意,在 Webpack 5 中应使用 type 而不是 test,否则除了 .css 文件之外,还可以生成一个额外的 .js 文件。这是因为 test 不知道应该删除哪些模块(在这种情况下,它不会检测到应该删除 .js)。

基于入口提取 CSS

您还可以根据 webpack 入口名称提取 CSS。如果您动态导入路由,但希望根据入口将 CSS 捆绑在一起,这将特别有用。这也避免了 ExtractTextPlugin 遇到的 CSS 重复问题。

const path = require("path");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  entry: {
    foo: path.resolve(__dirname, "src/foo"),
    bar: path.resolve(__dirname, "src/bar"),
  },
  optimization: {
    splitChunks: {
      cacheGroups: {
        fooStyles: {
          type: "css/mini-extract",
          name: "styles_foo",
          chunks: (chunk) => {
            return chunk.name === "foo";
          },
          enforce: true,
        },
        barStyles: {
          type: "css/mini-extract",
          name: "styles_bar",
          chunks: (chunk) => {
            return chunk.name === "bar";
          },
          enforce: true,
        },
      },
    },
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: "[name].css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};

作为函数的文件名选项

使用 filename 选项,您可以使用块数据自定义文件名。这在处理多个入口点并希望对给定入口点/块的文件名进行更多控制时特别有用。在下面的示例中,我们将使用 filename 将生成的 css 输出到不同的目录中。

webpack.config.js

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

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      filename: ({ chunk }) => `${chunk.name.replace("/js/", "/css/")}.css`,
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};

长期缓存

对于长期缓存,请使用 filename: "[contenthash].css"。可以选择添加 [name]

webpack.config.js

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

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      filename: "[name].[contenthash].css",
      chunkFilename: "[id].[contenthash].css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};

移除顺序警告

对于通过一致使用作用域或命名约定(例如 CSS Modules)来缓解 css 排序的项目,可以通过为插件设置 ignoreOrder 标志为 true 来禁用 css 顺序警告。

webpack.config.js

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

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      ignoreOrder: true,
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};

多个主题

webpack.config.js

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

module.exports = {
  entry: "./src/index.js",
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        oneOf: [
          {
            resourceQuery: "?dark",
            use: [
              MiniCssExtractPlugin.loader,
              "css-loader",
              {
                loader: "sass-loader",
                options: {
                  additionalData: `@use 'dark-theme/vars' as vars;`,
                },
              },
            ],
          },
          {
            use: [
              MiniCssExtractPlugin.loader,
              "css-loader",
              {
                loader: "sass-loader",
                options: {
                  additionalData: `@use 'light-theme/vars' as vars;`,
                },
              },
            ],
          },
        ],
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: "[name].css",
      attributes: {
        id: "theme",
      },
    }),
  ],
};

src/index.js

import "./style.scss";

let theme = "light";
const themes = {};

themes[theme] = document.querySelector("#theme");

async function loadTheme(newTheme) {
  // eslint-disable-next-line no-console
  console.log(`CHANGE THEME - ${newTheme}`);

  const themeElement = document.querySelector("#theme");

  if (themeElement) {
    themeElement.remove();
  }

  if (themes[newTheme]) {
    // eslint-disable-next-line no-console
    console.log(`THEME ALREADY LOADED - ${newTheme}`);

    document.head.appendChild(themes[newTheme]);

    return;
  }

  if (newTheme === "dark") {
    // eslint-disable-next-line no-console
    console.log(`LOADING THEME - ${newTheme}`);

    import(/* webpackChunkName: "dark" */ "./style.scss?dark").then(() => {
      themes[newTheme] = document.querySelector("#theme");

      // eslint-disable-next-line no-console
      console.log(`LOADED - ${newTheme}`);
    });
  }
}

document.onclick = () => {
  if (theme === "light") {
    theme = "dark";
  } else {
    theme = "light";
  }

  loadTheme(theme);
};

src/dark-theme/_vars.scss

$background: black;

src/light-theme/_vars.scss

$background: white;

src/styles.scss

body {
  background-color: vars.$background;
}

public/index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Document</title>
    <link id="theme" rel="stylesheet" type="text/css" href="./main.css" />
  </head>
  <body>
    <script src="./main.js"></script>
  </body>
</html>

媒体查询插件

如果您想从提取的 CSS 中提取媒体查询(以便移动用户不再需要加载桌面或平板电脑特定的 CSS),则应使用以下插件之一

钩子

mini-css-extract-plugin 提供钩子来扩展它以满足你的需求。

beforeTagInsert

SyncWaterfallHook

在注入链接标签的插入代码之前调用。应返回一个字符串

MiniCssExtractPlugin.getCompilationHooks(compilation).beforeTagInsert.tap(
  "changeHref",
  (source, varNames) =>
    Template.asString([
      source,
      `${varNames.tag}.setAttribute("href", "/plugins/mini-css-extract-plugin/));`,
    ])
);

贡献

如果你还没有这样做,请花点时间阅读我们的贡献指南。

贡献

许可证

MIT