css-loader

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

css-loader 将 @import 和 url() 解释为 import/require()，并将解析它们。

开始

警告
要使用 css-loader 的最新版本，需要 webpack@5

首先，你需要安装 css-loader

npm install --save-dev css-loader

或

yarn add -D css-loader

或

pnpm add -D css-loader

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

file.js

import css from "file.css";

webpack.config.js

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

并通过你喜欢的途径运行 webpack。

如果出于某种原因，你需要将 CSS 作为文件提取（即不将 CSS 存储在 JS 模块中），你可能需要查看推荐示例。

选项

url
import
modules
sourceMap
importLoaders
esModule
exportType

`url`

类型

type url =
  | boolean
  | {
      filter: (url: string, resourcePath: string) => boolean;
    };

默认值：true

允许启用/禁用处理 CSS 函数 url 和 image-set。如果设置为 false，css-loader 将不会解析在 url 或 image-set 中指定的任何路径。还可以传递一个函数，根据资产的路径动态控制此行为。从版本 4.0.0 开始，绝对路径将根据服务器根进行解析。

示例解析

url(image.png) => require('./image.png')
url('image.png') => require('./image.png')
url(./image.png) => require('./image.png')
url('./image.png') => require('./image.png')
url('http://dontwritehorriblecode.com/2112.png') => require('http://dontwritehorriblecode.com/2112.png')
image-set(url('image2x.png') 1x, url('image1x.png') 2x) => require('./image1x.png') and require('./image2x.png')

要从 node_modules 路径（包括 resolve.modules）导入资产，并为 alias，用 ~ 为其添加前缀

url(~module/image.png) => require('module/image.png')
url('~module/image.png') => require('module/image.png')
url(~aliasDirectory/image.png) => require('otherDirectory/image.png')

`boolean`

启用/禁用 url() 解析。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          url: true,
        },
      },
    ],
  },
};

`object`

允许过滤 url()。所有经过过滤的 url() 都不会被解析（保留在代码中，按原样编写）。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          url: {
            filter: (url, resourcePath) => {
              // resourcePath - path to css file

              // Don't handle `img.png` urls
              if (url.includes("img.png")) {
                return false;
              }

              // Don't handle images under root-relative /external_images/
              if (/^\/external_images\//.test(path)) {
                return false;
              }

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

`import`

类型

type importFn =
  | boolean
  | {
      filter: (
        url: string,
        media: string,
        resourcePath: string,
        supports?: string,
        layer?: string
      ) => boolean;
    };

默认值：true

允许启用/禁用 @import at 规则处理。控制 @import 解析。@import 中的绝对 URL 将在运行时代码中移动。

示例解析

@import 'style.css' => require('./style.css')
@import url(style.css) => require('./style.css')
@import url('style.css') => require('./style.css')
@import './style.css' => require('./style.css')
@import url(./style.css) => require('./style.css')
@import url('./style.css') => require('./style.css')
@import url('http://dontwritehorriblecode.com/style.css') => @import url('http://dontwritehorriblecode.com/style.css') in runtime

要从 node_modules 路径（包括 resolve.modules）导入样式，以及对于 alias，请在其前面加上 ~

@import url(~module/style.css) => require('module/style.css')
@import url('~module/style.css') => require('module/style.css')
@import url(~aliasDirectory/style.css) => require('otherDirectory/style.css')

`boolean`

启用/禁用 @import 解析。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          import: true,
        },
      },
    ],
  },
};

`object`

`filter`

类型

type filter = (url: string, media: string, resourcePath: string) => boolean;

默认值：undefined

允许过滤 @import。所有经过过滤的 @import 都不会被解析（保留在代码中，按原样编写）。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          import: {
            filter: (url, media, resourcePath) => {
              // resourcePath - path to css file

              // Don't handle `style.css` import
              if (url.includes("style.css")) {
                return false;
              }

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

`modules`

类型

type modules =
  | boolean
  | "local"
  | "global"
  | "pure"
  | "icss"
  | {
      auto: boolean | regExp | ((resourcePath: string) => boolean);
      mode:
        | "local"
        | "global"
        | "pure"
        | "icss"
        | ((resourcePath) => "local" | "global" | "pure" | "icss");
      localIdentName: string;
      localIdentContext: string;
      localIdentHashSalt: string;
      localIdentHashFunction: string;
      localIdentHashDigest: string;
      localIdentRegExp: string | regExp;
      getLocalIdent: (
        context: LoaderContext,
        localIdentName: string,
        localName: string
      ) => string;
      namedExport: boolean;
      exportGlobals: boolean;
      exportLocalsConvention:
        | "asIs"
        | "camelCase"
        | "camelCaseOnly"
        | "dashes"
        | "dashesOnly"
        | ((name: string) => string);
      exportOnlyLocals: boolean;
    };

默认值：undefined

允许启用/禁用 CSS 模块或 ICSS 并设置配置

undefined - 为所有匹配 /\.module\.\w+$/i.test(filename) 和 /\.icss\.\w+$/i.test(filename) 正则表达式的文件启用 CSS 模块。
true - 为所有文件启用 CSS 模块。
false - 为所有文件禁用 CSS 模块。
string - 为所有文件禁用 CSS 模块并设置 mode 选项，有关更多信息，请阅读此处
object - 为所有文件启用 CSS 模块，如果未指定 modules.auto 选项，则 modules.auto 选项将确定是否为 CSS 模块，有关更多信息，请阅读此处

modules 选项启用/禁用 CSS 模块 规范并设置基本行为。

使用 false 值会提高性能，因为我们避免解析 CSS 模块 特性，这对于使用原生 CSS 或使用其他技术的开发人员非常有用。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: true,
        },
      },
    ],
  },
};

`特性`

`范围`

使用 local 值要求您指定 :global 类。使用 global 值要求您指定 :local 类。使用 pure 值要求选择器必须至少包含一个本地类或 ID。

您可以在此处找到更多信息。

样式可以局部限定范围，以避免全局限定范围样式。

语法 :local(.className) 可用于在本地作用域中声明 className。本地标识符由模块导出。

使用 :local（无括号）可以为该选择器开启本地模式。:global(.className) 表示法可用于声明显式全局选择器。使用 :global（无括号）可以为该选择器开启全局模式。

加载器将本地选择器替换为唯一标识符。选定的唯一标识符由模块导出。

:local(.className) {
  background: red;
}
:local .className {
  color: green;
}
:local(.className .subClass) {
  color: green;
}
:local .className .subClass :global(.global-class-name) {
  color: blue;
}

._23_aKvs-b8bW2Vg3fwHozO {
  background: red;
}
._23_aKvs-b8bW2Vg3fwHozO {
  color: green;
}
._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 {
  color: green;
}
._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 .global-class-name {
  color: blue;
}

注意
标识符已导出

exports.locals = {
  className: "_23_aKvs-b8bW2Vg3fwHozO",
  subClass: "_13LGdX8RMStbBE9w-t0gZ1",
};

建议对本地选择器使用驼峰命名法。它们在导入的 JS 模块中更容易使用。

你可以使用 :local(#someId)，但不建议这样做。使用类而不是 ID。

`组合`

在声明本地类名时，你可以从另一个本地类名组合一个本地类。

:local(.className) {
  background: red;
  color: yellow;
}

:local(.subClass) {
  composes: className;
  background: blue;
}

这不会对 CSS 本身造成任何更改，但会导出多个类名。

exports.locals = {
  className: "_23_aKvs-b8bW2Vg3fwHozO",
  subClass: "_13LGdX8RMStbBE9w-t0gZ1 _23_aKvs-b8bW2Vg3fwHozO",
};

._23_aKvs-b8bW2Vg3fwHozO {
  background: red;
  color: yellow;
}

._13LGdX8RMStbBE9w-t0gZ1 {
  background: blue;
}

`导入`

要从另一个模块导入本地类名。

注意
我们强烈建议你在导入文件时指定扩展名，因为可以导入具有任何扩展名的文件，并且无法预先知道要使用哪个文件。

:local(.continueButton) {
  composes: button from "library/button.css";
  background: red;
}

:local(.nameEdit) {
  composes: edit highlight from "./edit.css";
  background: red;
}

要从多个模块导入，请使用多个 composes: 规则。

:local(.className) {
  composes: edit highlight from "./edit.css";
  composes: button from "module/button.css";
  composes: classFromThisModule;
  background: red;
}

`值`

你可以使用 @value 为将在整个文档中重复使用的值指定具体值。

我们建议对值使用前缀 v-，对选择器使用 s-，对媒体 at 规则使用 m-。

@value v-primary: #BF4040;
@value s-black: black-selector;
@value m-large: (min-width: 960px);

.header {
  color: v-primary;
  padding: 0 10px;
}

.s-black {
  color: black;
}

@media m-large {
  .header {
    padding: 0 20px;
  }
}

`布尔值`

启用 CSS 模块功能。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: true,
        },
      },
    ],
  },
};

`字符串`

启用 CSS 模块功能并设置 mode。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          // Using `local` value has same effect like using `modules: true`
          modules: "global",
        },
      },
    ],
  },
};

`object`

启用 CSS 模块 功能并为其设置选项。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            mode: "local",
            auto: true,
            exportGlobals: true,
            localIdentName: "[path][name]__[local]--[hash:base64:5]",
            localIdentContext: path.resolve(__dirname, "src"),
            localIdentHashSalt: "my-custom-hash",
            namedExport: true,
            exportLocalsConvention: "camelCase",
            exportOnlyLocals: false,
          },
        },
      },
    ],
  },
};

`auto`

类型

type auto =
  | boolean
  | regExp
  | ((
      resourcePath: string,
      resourceQuery: string,
      resourceFragment: string
    ) => boolean);

默认值：undefined

当 modules 选项为对象时，允许根据文件名、查询或片段自动启用 CSS 模块/ICSS。

可能的值

undefined - 为所有文件启用 CSS 模块。
true - 为所有与正则表达式 /\.module\.\w+$/i.test(filename) 和 /\.icss\.\w+$/i.test(filename) 匹配的文件启用 CSS 模块。
false - 禁用 CSS 模块。
RegExp - 为所有与正则表达式 /RegExp/i.test(filename) 匹配的文件启用 CSS 模块。
function - 根据满足筛选器函数检查的文件名，为文件启用 CSS 模块。

`boolean`

可能的值

true - 启用 CSS 模块或可互操作的 CSS 格式，为满足 /\.module(s)?\.\w+$/i.test(filename) 条件的所有文件将 modules.mode 选项设置为 local 值，或为满足 /\.icss\.\w+$/i.test(filename) 条件的所有文件将 modules.mode 选项设置为 icss 值
false - 根据文件名禁用 CSS 模块或可互操作的 CSS 格式

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            auto: true,
          },
        },
      },
    ],
  },
};

`RegExp`

根据满足正则表达式检查的文件名，为文件启用 CSS 模块。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            auto: /\.custom-module\.\w+$/i,
          },
        },
      },
    ],
  },
};

`function`

根据满足筛选器函数检查的文件名、查询或片段，为文件启用 CSS 模块。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            auto: (resourcePath, resourceQuery, resourceFragment) => {
              return resourcePath.endsWith(".custom-module.css");
            },
          },
        },
      },
    ],
  },
};

`mode`

类型

type mode =
  | "local"
  | "global"
  | "pure"
  | "icss"
  | ((
      resourcePath: string,
      resourceQuery: string,
      resourceFragment: string
    ) => "local" | "global" | "pure" | "icss");

默认值：'local'

设置 mode 选项。当您需要 local 模式时，可以省略该值。

控制应用于输入样式的编译级别。

local、global 和 pure 处理 class 和 id 范围以及 @value 值。icss 仅编译低级别的 可互操作 CSS 格式，用于声明 CSS 与其他语言之间的 :import 和 :export 依赖关系。

ICSS 支持 CSS 模块，并为其他工具提供低级语法，以便实现它们自己的 CSS 模块变体。

`string`

可能的值 - local、global、pure 和 icss。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            mode: "global",
          },
        },
      },
    ],
  },
};

`function`

允许根据文件名、查询或片段为 mode 选项设置不同的值。

可能的返回值 - local、global、pure 和 icss。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            // Callback must return "local", "global", or "pure" values
            mode: (resourcePath, resourceQuery, resourceFragment) => {
              if (/pure.css$/i.test(resourcePath)) {
                return "pure";
              }

              if (/global.css$/i.test(resourcePath)) {
                return "global";
              }

              return "local";
            },
          },
        },
      },
    ],
  },
};

`localIdentName`

类型

type localIdentName = string;

默认值：'[hash:base64]'

允许配置生成的本地标识名称。

有关选项的更多信息，请参阅

支持的模板字符串

[name] 资源的基本名称
[folder] 资源相对于 compiler.context 选项或 modules.localIdentContext 选项的文件夹。
[path] 资源相对于 compiler.context 选项或 modules.localIdentContext 选项的路径。
[file] - 文件名和路径。
[ext] - 带前导 . 的扩展名。
[hash] - 字符串的哈希，根据 localIdentHashSalt、localIdentHashFunction、localIdentHashDigest、localIdentHashDigestLength、localIdentContext、resourcePath 和 exportName 生成
[<hashFunction>:hash:<hashDigest>:<hashDigestLength>] - 带有哈希设置的哈希。
[local] - 原始类。

建议

在开发中使用 '[path][name]__[local]'
在生产中使用 '[hash:base64]'

[local] 占位符包含原始类。

注意：所有保留的（<>:"/\|?*）和控制文件系统字符（不包括 [local] 占位符中的字符）都将转换为 -。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentName: "[path][name]__[local]--[hash:base64:5]",
          },
        },
      },
    ],
  },
};

`localIdentContext`

类型

type localIdentContex = string;

默认值：compiler.context

允许为本地标识名称重新定义基本加载器上下文。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentContext: path.resolve(__dirname, "src"),
          },
        },
      },
    ],
  },
};

`localIdentHashSalt`

类型

type localIdentHashSalt = string;

默认值：undefined

允许添加自定义哈希以生成更多唯一的类。有关更多信息，请参阅 output.hashSalt。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentHashSalt: "hash",
          },
        },
      },
    ],
  },
};

`localIdentHashFunction`

类型

type localIdentHashFunction = string;

默认值：md4

允许指定哈希函数来生成类。有关更多信息，请参阅 output.hashFunction。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentHashFunction: "md4",
          },
        },
      },
    ],
  },
};

`localIdentHashDigest`

类型

type localIdentHashDigest = string;

默认值：hex

允许指定哈希摘要来生成类。有关更多信息，请参阅 output.hashDigest。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentHashDigest: "base64",
          },
        },
      },
    ],
  },
};

`localIdentHashDigestLength`

类型

type localIdentHashDigestLength = number;

默认值：20

允许指定哈希摘要长度来生成类。有关更多信息，请参阅 output.hashDigestLength。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentHashDigestLength: 5,
          },
        },
      },
    ],
  },
};

`hashStrategy`

类型：'resource-path-and-local-name' | 'minimal-subset' 默认值：'resource-path-and-local-name'

计算哈希时是否应使用本地名称。

'resource-path-and-local-name' 哈希时同时使用资源路径和本地名称。模块中的每个标识符始终获得自己的哈希摘要。
'minimal-subset' 自动检测是否可以从哈希中省略标识符名称。使用此值可以优化输出，以获得更好的 GZIP 或 Brotli 压缩。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            hashStrategy: "minimal-subset",
          },
        },
      },
    ],
  },
};

`localIdentRegExp`

类型

type localIdentRegExp = string | RegExp;

默认值：undefined

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentRegExp: /page-(.*)\.css/i,
          },
        },
      },
    ],
  },
};

`getLocalIdent`

类型

type getLocalIdent = (
  context: LoaderContext,
  localIdentName: string,
  localName: string
) => string;

默认值：undefined

允许指定一个函数来生成类名。默认情况下，我们使用内置函数来生成类名。如果自定义函数返回 null 或 undefined，我们将回退到内置函数来生成类名。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            getLocalIdent: (context, localIdentName, localName, options) => {
              return "whatever_random_class_name";
            },
          },
        },
      },
    ],
  },
};

`namedExport`

类型

type namedExport = boolean;

默认值：false

启用/禁用局部变量的 ES 模块命名导出。

警告
局部变量的名称转换为驼峰式，即 exportLocalsConvention 选项默认具有 camelCaseOnly 值。你可以将其设置回任何其他有效选项，但不是有效 JavaScript 标识符的选择器可能会遇到未实现整个模块规范的问题。

警告
除非 exportLocalsConvention 为 "asIs"，否则不允许在 CSS 类名中使用 JavaScript 保留字。

styles.css

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

index.js

import * as styles from "./styles.css";

console.log(styles.fooBaz, styles.bar);
// or if using `exportLocalsConvention: "asIs"`:
console.log(styles["foo-baz"], styles.bar);

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

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          esModule: true,
          modules: {
            namedExport: true,
          },
        },
      },
    ],
  },
};

要为命名导出设置自定义名称，可以使用 exportLocalsConvention 选项作为函数。示例如下，在 examples 部分中。

`exportGlobals`

类型

type exportsGLobals = boolean;

默认值：false

允许 css-loader 从全局类或 ID 中导出名称，以便你可以将其用作本地名称。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            exportGlobals: true,
          },
        },
      },
    ],
  },
};

`exportLocalsConvention`

类型

type exportLocalsConvention =
  | "asIs"
  | "camelCase"
  | "camelCaseOnly"
  | "dashes"
  | "dashesOnly"
  | ((name: string) => string);

默认：基于 modules.namedExport 选项值，如果为 true - camelCaseOnly，否则为 asIs

导出的类名的样式。

`string`

默认情况下，导出的 JSON 键反映类名（即 asIs 值）。

名称	类型	描述
`'asIs'`	`string`	类名将按原样导出。
`'camelCase'`	`string`	类名将采用驼峰式命名，原始类名将不会从本地变量中删除
`'camelCaseOnly'`	`string`	类名将采用驼峰式命名，原始类名将从本地变量中删除
`'dashes'`	`string`	类名中只有破折号将采用驼峰式命名
`'dashesOnly'`	`string`	类名中的破折号将采用驼峰式命名，原始类名将从本地变量中删除

file.css

.class-name {
}

file.js

import { className } from "file.css";

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            exportLocalsConvention: "camelCase",
          },
        },
      },
    ],
  },
};

`function`

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            exportLocalsConvention: function (name) {
              return name.replace(/-/g, "_");
            },
          },
        },
      },
    ],
  },
};

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            exportLocalsConvention: function (name) {
              return [
                name.replace(/-/g, "_"),
                // dashesCamelCase
                name.replace(/-+(\w)/g, (match, firstLetter) =>
                  firstLetter.toUpperCase()
                ),
              ];
            },
          },
        },
      },
    ],
  },
};

`exportOnlyLocals`

类型

type exportOnlyLocals = boolean;

默认值：false

仅导出本地变量。

当您将 css 模块用于预渲染（例如 SSR）时，很有用。对于使用 mini-css-extract-plugin 进行预渲染，您应该在 预渲染包中使用此选项，而不是 style-loader!css-loader。它不嵌入 CSS，而仅导出标识符映射。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            exportOnlyLocals: true,
          },
        },
      },
    ],
  },
};

`importLoaders`

类型

type importLoaders = number;

默认：0

允许启用/禁用或设置在 @import at 规则、CSS 模块和 ICSS 导入之前应用于 CSS 加载器的加载器数量，即 @import/composes/@value value from './values.css'/等。

importLoaders 选项允许您配置在 css-loader 之前应用于 @imported 资源和 CSS 模块/ICSS 导入的加载器数量。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              importLoaders: 2,
              // 0 => no loaders (default);
              // 1 => postcss-loader;
              // 2 => postcss-loader, sass-loader
            },
          },
          "postcss-loader",
          "sass-loader",
        ],
      },
    ],
  },
};

当模块系统（即 webpack）按来源支持加载器匹配时，这可能会在未来发生变化。

`sourceMap`

类型

type sourceMap = boolean;

默认：取决于 compiler.devtool 值

默认情况下，源映射的生成取决于 devtool 选项。除 eval 和 false 值外，所有值均启用源映射生成。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          sourceMap: true,
        },
      },
    ],
  },
};

`esModule`

类型

type esModule = boolean;

默认值：true

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

您可以使用以下方法启用 CommonJS 模块语法

webpack.config.js

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

`exportType`

类型

type exportType = "array" | "string" | "css-style-sheet";

默认：'array'

允许将样式作为带有模块、字符串或可构造样式表（即 CSSStyleSheet）的数组导出。默认值为 'array'，即加载器导出带有特定 API 的模块数组，该 API 在 style-loader 或其他模块中使用。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        assert: { type: "css" },
        loader: "css-loader",
        options: {
          exportType: "css-style-sheet",
        },
      },
    ],
  },
};

src/index.js

import sheet from "./styles.css" assert { type: "css" };

document.adoptedStyleSheets = [sheet];
shadowRoot.adoptedStyleSheets = [sheet];

`'array'`

默认导出项是带有特定 API 的模块数组，该 API 在 style-loader 或其他模块中使用。

webpack.config.js

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

src/index.js

// `style-loader` applies styles to DOM
import "./styles.css";

`'string'`

警告
不要将 style-loader 或 mini-css-extract-plugin 与此值一起使用。

警告
如果你想将 esModule 选项与 CSS 模块 一起使用，则应启用该选项，默认情况下，对于本地模块将使用命名导出。

默认导出项是 string。

webpack.config.js

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

src/index.js

import sheet from "./styles.css";

console.log(sheet);

`'css-style-sheet'`

警告
@import 规则尚未允许，更多信息

警告
你不再需要 style-loader，请将其移除。

警告
如果你想将 esModule 选项与 CSS 模块 一起使用，则应启用该选项，默认情况下，对于本地模块将使用命名导出。

警告
由于错误，源映射目前在 Chrome 中不受支持

默认导出项是可构造样式表（即 CSSStyleSheet）。

对自定义元素和影子 DOM 有用。

更多信息

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        assert: { type: "css" },
        loader: "css-loader",
        options: {
          exportType: "css-style-sheet",
        },
      },

      // For Sass/SCSS:
      //
      // {
      //   assert: { type: "css" },
      //   rules: [
      //     {
      //       loader: "css-loader",
      //       options: {
      //         exportType: "css-style-sheet",
      //         // Other options
      //       },
      //     },
      //     {
      //       loader: "sass-loader",
      //       options: {
      //         // Other options
      //       },
      //     },
      //   ],
      // },
    ],
  },
};

src/index.js

// Example for Sass/SCSS:
// import sheet from "./styles.scss" assert { type: "css" };

// Example for CSS modules:
// import sheet, { myClass } from "./styles.scss" assert { type: "css" };

// Example for CSS:
import sheet from "./styles.css" assert { type: "css" };

document.adoptedStyleSheets = [sheet];
shadowRoot.adoptedStyleSheets = [sheet];

出于迁移目的，你可以使用以下配置

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        oneOf: [
          {
            assert: { type: "css" },
            loader: "css-loader",
            options: {
              exportType: "css-style-sheet",
              // Other options
            },
          },
          {
            use: [
              "style-loader",
              {
                loader: "css-loader",
                options: {
                  // Other options
                },
              },
            ],
          },
        ],
      },
    ],
  },
};

示例

使用 `/* webpackIgnore: true */` 注释禁用 URL 解析

借助 /* webpackIgnore: true */ 注释，可以禁用规则和各个声明的源处理。

/* webpackIgnore: true */
@import url(./basic.css);
@import /* webpackIgnore: true */ url(./imported.css);

.class {
  /* Disabled url handling for the all urls in the 'background' declaration */
  color: red;
  /* webpackIgnore: true */
  background: url("./url/img.png"), url("./url/img.png");
}

.class {
  /* Disabled url handling for the first url in the 'background' declaration */
  color: red;
  background:
    /* webpackIgnore: true */ url("./url/img.png"), url("./url/img.png");
}

.class {
  /* Disabled url handling for the second url in the 'background' declaration */
  color: red;
  background: url("./url/img.png"),
    /* webpackIgnore: true */ url("./url/img.png");
}

/* prettier-ignore */
.class {
  /* Disabled url handling for the second url in the 'background' declaration */
  color: red;
  background: url("./url/img.png"),
    /* webpackIgnore: true */
    url("./url/img.png");
}

/* prettier-ignore */
.class {
  /* Disabled url handling for third and sixth urls in the 'background-image' declaration */
  background-image: image-set(
    url(./url/img.png) 2x,
    url(./url/img.png) 3x,
    /* webpackIgnore:  true */ url(./url/img.png) 4x,
    url(./url/img.png) 5x,
    url(./url/img.png) 6x,
    /* webpackIgnore:  true */
    url(./url/img.png) 7x
  );
}

资产

以下 webpack.config.js 可以加载 CSS 文件，嵌入小型 PNG/JPG/GIF/SVG 图像以及字体作为数据 URL，并将较大的文件复制到输出目录。

对于 webpack v5

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader"],
      },
      {
        test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
        // More information here https://webpack.js.cn/guides/asset-modules/
        type: "asset",
      },
    ],
  },
};

提取

对于生产构建，建议从捆绑包中提取 CSS，以便以后能够并行加载 CSS/JS 资源。

这可以通过在生产模式下运行时使用 mini-css-extract-plugin 来提取 CSS 来实现。
或者，如果寻求更好的开发性能和模仿生产的 css 输出。extract-css-chunks-webpack-plugin 提供了一个热模块重新加载友好的 mini-css-extract-plugin 扩展版本。在开发中 HMR 真实 CSS 文件，在非开发中像 mini-css 一样工作

纯 CSS、CSS 模块和 PostCSS

当您的项目中包含纯 CSS（不含 CSS 模块）、CSS 模块和 PostCSS 时，可以使用此设置

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        // For pure CSS - /\.css$/i,
        // For Sass/SCSS - /\.((c|sa|sc)ss)$/i,
        // For Less - /\.((c|le)ss)$/i,
        test: /\.((c|sa|sc)ss)$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              // Run `postcss-loader` on each CSS `@import` and CSS modules/ICSS imports, do not forget that `sass-loader` compile non CSS `@import`'s into a single file
              // If you need run `sass-loader` and `postcss-loader` on each CSS `@import` please set it to `2`
              importLoaders: 1,
            },
          },
          {
            loader: "postcss-loader",
            options: { plugins: () => [postcssPresetEnv({ stage: 0 })] },
          },
          // Can be `less-loader`
          {
            loader: "sass-loader",
          },
        ],
      },
      // For webpack v5
      {
        test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
        // More information here https://webpack.js.cn/guides/asset-modules/
        type: "asset",
      },
    ],
  },
};

使用别名解析未解析的 URL

index.css

.class {
  background: url(/assets/unresolved/img.png);
}

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader"],
      },
    ],
  },
  resolve: {
    alias: {
      "/assets/unresolved/img.png": path.resolve(
        __dirname,
        "assets/real-path-to-img/img.png"
      ),
    },
  },
};

使用自定义导出名称的命名导出

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            namedExport: true,
            exportLocalsConvention: function (name) {
              return name.replace(/-/g, "_");
            },
          },
        },
      },
    ],
  },
};

分离仅 `Interoperable CSS` 和 `CSS Module` 特性

以下设置是一个示例，允许仅使用 Interoperable CSS 特性（例如 :import 和 :export），而不使用进一步的 CSS Module 功能，方法是为所有不匹配 *.module.scss 命名约定的文件设置 mode 选项。这是为了参考，因为在 v4 之前将 ICSS 特性应用于所有文件是 css-loader 的默认行为。同时，在此示例中，所有匹配 *.module.scss 的文件都被视为 CSS Modules。

假设一个示例案例，其中项目需要将画布绘制变量与 CSS 同步 - 画布绘制使用与 HTML 背景（由 CSS 中的类名设置）相同的颜色（由 JavaScript 中的颜色名称设置）。

webpack.config.js

module.exports = {
  module: {
    rules: [
      // ...
      // --------
      // SCSS ALL EXCEPT MODULES
      {
        test: /\.scss$/i,
        exclude: /\.module\.scss$/i,
        use: [
          {
            loader: "style-loader",
          },
          {
            loader: "css-loader",
            options: {
              importLoaders: 1,
              modules: {
                mode: "icss",
              },
            },
          },
          {
            loader: "sass-loader",
          },
        ],
      },
      // --------
      // SCSS MODULES
      {
        test: /\.module\.scss$/i,
        use: [
          {
            loader: "style-loader",
          },
          {
            loader: "css-loader",
            options: {
              importLoaders: 1,
              modules: {
                mode: "local",
              },
            },
          },
          {
            loader: "sass-loader",
          },
        ],
      },
      // --------
      // ...
    ],
  },
};

variables.scss

文件被视为仅 ICSS。

$colorBackground: red;
:export {
  colorBackgroundCanvas: $colorBackground;
}

Component.module.scss

文件视为 CSS 模块。

@import "variables.scss";
.componentClass {
  background-color: $colorBackground;
}

Component.jsx

在 JavaScript 中直接使用 CSS 模块功能和 SCSS 变量。

import svars from "variables.scss";
import styles from "Component.module.scss";

// Render DOM with CSS modules class name
// <div className={styles.componentClass}>
//   <canvas ref={mountsCanvas}/>
// </div>

// Somewhere in JavaScript canvas drawing code use the variable directly
// const ctx = mountsCanvas.current.getContext('2d',{alpha: false});
ctx.fillStyle = `${svars.colorBackgroundCanvas}`;

贡献

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

贡献

许可证

« 上一页

css-loader

开始

选项

url

boolean

object

import

boolean

object

filter

modules

特性

范围

组合

导入

值

布尔值

字符串

object

auto

boolean

RegExp

function

mode

string

function

localIdentName

localIdentContext

localIdentHashSalt

localIdentHashFunction

localIdentHashDigest

localIdentHashDigestLength

hashStrategy

localIdentRegExp

getLocalIdent

namedExport

exportGlobals

exportLocalsConvention

string

function

exportOnlyLocals

importLoaders

sourceMap

esModule

exportType

'array'

'string'

'css-style-sheet'

示例

推荐

使用 /* webpackIgnore: true */ 注释禁用 URL 解析

资产

提取

纯 CSS、CSS 模块和 PostCSS

使用别名解析未解析的 URL

使用自定义导出名称的命名导出

分离仅 Interoperable CSS 和 CSS Module 特性

贡献

许可证

`url`

`boolean`

`object`

`import`

`boolean`

`object`

`filter`

`modules`

`特性`

`范围`

`组合`

`导入`

`值`

`布尔值`

`字符串`

`object`

`auto`

`boolean`

`RegExp`

`function`

`mode`

`string`

`function`

`localIdentName`

`localIdentContext`

`localIdentHashSalt`

`localIdentHashFunction`

`localIdentHashDigest`

`localIdentHashDigestLength`

`hashStrategy`

`localIdentRegExp`

`getLocalIdent`

`namedExport`

`exportGlobals`

`exportLocalsConvention`

`string`

`function`

`exportOnlyLocals`

`importLoaders`

`sourceMap`

`esModule`

`exportType`

`'array'`

`'string'`

`'css-style-sheet'`

使用 `/* webpackIgnore: true */` 注释禁用 URL 解析

分离仅 `Interoperable CSS` 和 `CSS Module` 特性