close
  • 简体中文

      • CssExtractRspackPlugin

      Rspack only

      Rspack 目前不兼容 mini-css-extract-plugin，但可以使用 CssExtractRspackPlugin 替代，它可以和 css-loader 搭配使用，用于将 CSS 提取成单独文件。

      如果你的项目不依赖于 css-loader 和 mini-css-extract-plugin，我们更推荐使用 Rspack 内置的 CSS 解决方案，它的性能更好。

      示例

      使用 CssExtractRspackPlugin 时，需要在 plugins 中注册插件，并在 module.rules 中注册 CssExtractRspackPlugin.loader。

      rspack.config.mjs
      import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.CssExtractRspackPlugin({})],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
        type: 'javascript/auto',
      },
    ],
  },
};

      通过 splitChunks 拆分提取出的 CSS

      CssExtractRspackPlugin 会为提取出的 CSS 模块添加 css/mini-extract 模块类型。你可以使用 splitChunks.cacheGroups.{cacheGroup}.type 创建一个只命中 CssExtractRspackPlugin 提取出的 CSS 的 cache group，而不会命中 JavaScript 模块或内置 CSS 模块。

      rspack.config.mjs
      import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.CssExtractRspackPlugin({})],
  module: {
    rules: [
      {
        test: /\.css$/i,
        type: 'javascript/auto',
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
      },
    ],
  },
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        extractedCss: {
          type: 'css/mini-extract',
          name: 'styles',
          chunks: 'all',
          enforce: true,
        },
      },
    },
  },
};

      在这个例子中，extractedCss 只会选择模块类型为 css/mini-extract 的模块。enforce: true 会让 CSS chunk 即使在普通 minSize 或请求数限制启发式规则下会被跳过时也被创建；如果希望该 cache group 遵循普通 splitChunks 启发式规则，可以移除 enforce。

      Plugin 选项

      CssExtractRspackPlugin 插件的选项。

      • Types:
      interface PluginOptions {
  filename?: string | ((pathData: PathData, assetInfo?: AssetInfo) => string);
  chunkFilename?:
    | string
    | ((pathData: PathData, assetInfo?: AssetInfo) => string);
  ignoreOrder?: boolean;
  insert?: string | ((linkTag: HTMLLinkElement) => void);
  attributes?: Record<string, string>;
  linkType?: string | 'text/css' | false;
  runtime?: boolean;
  pathinfo?: boolean;
  enforceRelative?: boolean;
}
      名称类型默认值描述
      filenamestring"[name].css"CSS 产物的名称，请参考 output.filename
      chunkFilenamestring"[name].css"异步加载的 CSS 产物的名称，如果不设置则会使用 filename，请参考 output.chunkFilename
      ignoreOrderbooleanfalse若某些 CSS 在不同 chunk 中顺序有冲突，是否发出警告。例如 entryA 引入 a.css 和 b.css，entryB 引入 b.css 和 a.css，a.css 和 b.css 的顺序无法确定
      insertstring | ((linkTag: HTMLLinkElement) => void)undefined决定 link 标签怎样插入到页面，如果传入 string 类型，则会视为 DOM 选择器，link 标签会插入到该选择器对应的元素后。如果传入 function 类型，则会将 function 转成字符串，在运行时进行调用，参数是 link 标签
      attributesRecord<string, string>undefined设置 link 标签的自定义 attributes，仅对异步加载的 CSS 文件生效
      linkTypestring | 'text/css' | false"text/css"设置 link 标签的 type 属性值，仅对异步加载的 CSS 文件生效
      runtimebooleantrue是否注入 runtime 代码以加载 CSS。如果禁用，CSS 仍然会被提取，可用于自定义的加载方式
      pathinfobooleanfalse是否在 CSS 产物中包含带有更详细的路径信息的注释
      enforceRelativebooleanfalse是否在生成的 CSS url() 是相对路径时，保留 "./"

      Loader 选项

      CssExtractRspackPlugin.loader 的选项。

      • Types:
      interface LoaderOptions {
  publicPath?: string | ((resourcePath: string, context: string) => string);
  emit?: boolean;
  esModule?: boolean;
}
      名称类型默认值描述
      publicPathstring | ((resourcePath: string, context: string) => string)output.publicPath为 CSS 中的外部资源（如图片、文件等）指定自定义的 publicPath
      emitbooleantrue如果为 true，则输出 CSS 文件。如果为 false，则插件将提取 CSS，但不会输出文件
      esModulebooleantrue在生成的 JavaScript 模块中，是否使用 ES 模块语法进行 CSS Modules 类名导出

      注意事项

      当同时使用内置 CSS 和 CssExtractRspackPlugin 时，推荐显式手动给 CssExtractRspackPlugin.loader 的 type 设置成 javascript/auto。

      例如：

      rspack.config.mjs
      import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.CssExtractRspackPlugin({})],
  module: {
    rules: [
      {
        test: /src\/legacy-project\/.*\.css$/,
        type: 'javascript/auto', // 覆盖默认的 CSS 模块类型，视为普通 JS 文件
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
      },
      {
        test: /src\/new-project\/.*\.css$/,
        type: 'css/auto', // 使用内置 CSS 处理
      },
    ],
  },
  experiments: {
    css: true,
  },
};