css-loader
会对 @import
和 url()
进行处理,就像 js 解析 import/require()
一样。
如果要使用 css-loader,你需要安装 webpack@5
首先,你需要先安装 css-loader
:
npm install --save-dev css-loader
然后把 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 | {Boolean|Function} | true | 启用/禁用 url() /image-set() 函数处理 |
import | {Boolean|Function} | true | 启用/禁用 @import 规则进行处理 |
modules | {Boolean|String|Object} | {auto: true} | 启用/禁用 CSS 模块及其配置 |
sourceMap | {Boolean} | compiler.devtool | 启用/禁用生成 SourceMap |
importLoaders | {Number} | 0 | 启用/禁用或者设置在 css-loader 前应用的 loader 数量 |
esModule | {Boolean} | true | 使用 ES 模块语法 |
exportType | {'array' | 'string' | 'css-style-sheet'} | array | 允许导出样式为模块数组、字符串或者 可构造样式(即 CSSStyleSheet ) |
url
类型: Boolean|Object
默认值: true
启用/禁用 url
/image-set
函数进行处理。
如果设置为 false
,css-loader
将不会解析 url
或者 image-set
中的任何路径。
还可以传递给一个函数基于资源的路径动态地控制这种行为。
绝对路径和根目录的相对 URL 现在会被解析(版本 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 - css 文件的路径
// 不处理 `img.png` url
if (url.includes('img.png')) {
return false;
}
return true;
},
},
},
},
],
},
};
import
类型: Boolean|Object
默认值: true
启用/禁用 @import
规则进行处理。
控制 @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 | {Function} | undefined | 允许过滤 @import |
filter
类型:Function
默认值:undefined
允许过滤 @import
。所有过滤的内容 @import
都不会解析(保留编写时的代码)。
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
options: {
import: {
filter: (url, media, resourcePath) => {
// resourcePath - css 文件路径
// 不处理 `style.css` 的导入
if (url.includes('style.css')) {
return false;
}
return true;
},
},
},
},
],
},
};
modules
类型:Boolean|String|Object
默认值:undefined
启用/禁用 CSS 模块或者 ICSS 及其配置:
undefined
- 为所有匹配 /\.module\.\w+$/i.test(filename)
与 /\.icss\.\w+$/i.test(filename)
正则表达式的文件启用 CSS 模块。true
- 对所有文件启用 CSS 模块。false
- 对所有文件禁用 CSS 模块。string
- 对所有文件禁用 CSS 模块并设置 mode
配置项,你可以在 这里 获得更多信息。object
- 如果没有配置 modules.auto
则对所有文件启用 CSS 模块,否则 modules.auto
配置项则会决定其是否为 CSS 模块,你可以在 这里 获得更多信息。该 modules
选项启用/禁用 CSS 模块 规范并且设置基本的行为。
设置为 false
值会提升性能,因为避免了 CSS Modules 特性的解析,这对于使用普通 CSS 或者其他技术的开发人员是非常有用的。
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
options: {
modules: true,
},
},
],
},
};
Features
Scope
使用 local
值要求你指定 :global
类。
使用 global
值要求你指定 :local
类。
使用 pure
值则要求必须至少包含一个局部类或者 id。
你可以点击 此处 了解更多。
样式可以在局部作用域中,避免影响全局作用域的样式。
语法 :local(.className)
可以被用来在局部作用域中声明 className。局部的作用域标识符会以模块形式暴露出去。
使用 :local
(无括号)可以为此选择器启用局部模式。
:global(.className)
可以用来声明一个明确的全局选择器。
使用 :global
(无括号)可以将此选择器切换至全局模式。
loader 会用唯一的标识符 (identifier) 来替换局部选择器。所选择的唯一标识符以模块形式暴露出去。
: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。
Composing
声明本地类名时,可以从另一个本地类名组成一个本地类。
: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;
}
Importing
从另一个模块导入本地类名。
我强烈建议您在导入文件时指定扩展名,因为可以导入具有任何扩展名的文件,而且事先并不能知道要使用哪个文件。
: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 hightlight from './edit.css';
composes: button from 'module/button.css';
composes: classFromThisModule;
background: red;
}
Values
可以使用 @value
来指定在整个文档中都能被重复使用的值,
我们推荐对特定的值使用 v-
的前缀,给选择器使用 s-
的前缀,并且为媒体规则使用 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;
}
}
Boolean
启用 CSS 模块 功能。
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
options: {
modules: true,
},
},
],
},
};
String
启用 CSS 模块 功能和设置 mode
。
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
options: {
// 使用 `local` 同使用 `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
类型:Boolean|RegExp|Function
默认值: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) => resourcePath.endsWith('.custom-module.css'),
},
},
},
],
},
};
mode
类型:String|Function
默认:'local'
设置 mode
选项。需要 local
模式时可以忽略该值。
控制应用于输入样式的编译级别。
local
、global
和 pure
处理 class
和 id
域以及 @value
值。
icss
只会编译底层的 Interoperable CSS
格式,用于声明 CSS 和其他语言之间的 :import
和 :export
依赖关系。
ICSS 提供 CSS Module 支持,并且为其他工具提供了一个底层语法,以实现它们自己的 css-module 变体。
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: {
// 回调必须返回 `local`,`global`,或者 `pure`
mode: (resourcePath) => {
if (/pure.css$/i.test(resourcePath)) {
return 'pure';
}
if (/global.css$/i.test(resourcePath)) {
return 'global';
}
return 'local';
},
},
},
},
],
},
};
localIdentName
类型:String
默认:'[hash:base64]'
允许配置生成的本地标识符(ident)。
更多关于配置项的信息可以查看:
支持的模板字符串:
[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
类型:String
默认:compiler.context
允许为本地标识符名称重新定义基本的 loader 上下文。
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
options: {
modules: {
localIdentContext: path.resolve(__dirname, 'src'),
},
},
},
],
},
};
localIdentHashSalt
类型:String
默认:undefined
允许添加自定义哈希值以生成更多唯一类。 更多信息请查看 output.hashSalt。
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
options: {
modules: {
localIdentHashSalt: 'hash',
},
},
},
],
},
};
localIdentHashFunction
类型:String
默认值:md4
允许设置生成 class 的哈希函数。 更多信息请查看 output.hashFunction。
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
options: {
modules: {
localIdentHashFunction: 'md4',
},
},
},
],
},
};
localIdentHashDigest
类型:String
默认值:hex
允许设置生成 class 的哈希摘要。 更多信息请查看 output.hashDigest。
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
options: {
modules: {
localIdentHashDigest: 'base64',
},
},
},
],
},
};
localIdentHashDigestLength
$#localidentHashdigestlength$类型:Number
默认值:20
允许设置生成 class 的哈希摘要长度。 更多信息请查看 output.hashDigestLength。
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
options: {
modules: {
localIdentHashDigestLength: 5,
},
},
},
],
},
};
localIdentRegExp
类型:String|RegExp
默认:undefined
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
options: {
modules: {
localIdentRegExp: /page-(.*)\.css/i,
},
},
},
],
},
};
getLocalIdent
类型:Function
默认:undefined
可以指定自定义 getLocalIdent
函数的绝对路径,以基于不同的架构生成类名。
默认情况下,我们使用内置函数来生成 classname。
如果自定义函数返回 null
或者 undefined
,
我们将降级使用内置函数来生成 classname。
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
类型:Boolean
默认:false
本地环境启用/禁用 export 的 ES 模块。
⚠ 本地环境的命名将转换为驼峰格式,即
exportLocalsConvention
选项默认设置了camelCaseOnly
。
⚠ 不允许在 CSS 类名中使用 JavaScript 保留字。
styles.css
.foo-baz {
color: red;
}
.bar {
color: blue;
}
index.js
import { fooBaz, bar } from './styles.css';
console.log(fooBaz, bar);
可以使用以下命令启用 export 的 ES 模块:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
options: {
esModule: true,
modules: {
namedExport: true,
},
},
},
],
},
};
可以为 namedExport 设置一个自定义名称,可以使用 exportLocalsConvention
配置项作为一个函数。
可前往 examples
章节查看示例。
exportGlobals
类型:Boolean
默认:false
允许 css-loader
从全局类或 ID 导出名称,因此您可以将其用作本地名称。
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
options: {
modules: {
exportGlobals: true,
},
},
},
],
},
};
exportLocalsConvention
类型:String|Function
默认:取决于 modules.namedExport
选项值,如果为 true
则对应的是 camelCaseOnly
,反之对应的是 asIs
导出的类名称的样式。
String
默认情况下,导出的 JSON 密钥反映了类名(即 asIs
值)。
⚠ 如果你设置
namedExport
为true
那么只有camelCaseOnly
被允许。
名称 | 类型 | 描述 |
---|---|---|
'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
类型: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
类型:Number
默认:0
允许为 @import
样式规则、CSS 模块或者 ICSS 启用/禁用或设置在 CSS loader 之前应用的 loader 的数量,例如:@import
/composes
/@value value from './values.css'
等。
importLoaders
选项允许你配置在 css-loader
之前有多少 loader 应用于 @import
ed 资源与 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)支持按来源匹配 loader 时,这种情况将来可能会改变。
sourceMap
类型:Boolean
默认值:取决于 compiler.devtool
值
source map 的生成默认依赖 devtool
配置项。除了 eval
与 false
之外的值都会启用 source map。
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
options: {
sourceMap: true,
},
},
],
},
};
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
类型:'array' | 'string' | 'css-style-sheet'
默认值:'array'
允许导出样式为模块数组、字符串或者 可构造样式(即 CSSStyleSheet
)。
默认值为 'array'
,即 loader 导出具有特定 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'
loader 导出具有特定 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
,请移除它。 ⚠ 如果你想使用CSS modules
,应该启用esModules
配置项,默认情况下,本地变量会被 具名导出。
默认导出为 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
,请移除它。 ⚠ 如果你想使用CSS modules
,应该启用esModules
配置项,默认情况下,本地变量会被 具名导出。 ⚠ 目前在Chrome
中不支持 Source maps,因为有该 bug
默认导出是一个 可构造样式 (即 CSSStyleSheet
)。
对 自定义元素 以及 shadow 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
},
},
],
},
],
},
],
},
};
推荐 production
环境的构建将 CSS 从你的 bundle 中分离出来,这样可以使用 CSS/JS 文件的并行加载。
这可以通过使用 mini-css-extract-plugin
来实现,因为它可以创建单独的 CSS 文件。
对于 development
模式(包括 webpack-dev-server
),你可以使用 style-loader,因为它可以使用多个 标签将 CSS 插入到 DOM 中,并且反应会更快。
i 不要同时使用
style-loader
与mini-css-extract-plugin
。
webpack.config.js
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const devMode = process.env.NODE_ENV !== 'production';
module.exports = {
module: {
rules: [
{
test: /\.(sa|sc|c)ss$/i,
use: [
devMode ? 'style-loader' : MiniCssExtractPlugin.loader,
'css-loader',
'postcss-loader',
'sass-loader',
],
},
],
},
plugins: [].concat(devMode ? [] : [new MiniCssExtractPlugin()]),
};
/* webpackIgnore: true */
注释禁用 url 解析有了 /* webpackIgnore: true */
注释,可以禁用对规则和单个声明的源处理。
/* webpackIgnore: true */
@import url(./basic.css);
@import /* webpackIgnore: true */ url(./imported.css);
.class {
/* 对 'background' 声明中的所有 url 禁用 url 处理 */
color: red;
/* webpackIgnore: true */
background: url('./url/img.png'), url('./url/img.png');
}
.class {
/* 对 'background' 声明中第一个 url 禁用 url 处理 */
color: red;
background:
/* webpackIgnore: true */ url('./url/img.png'), url('./url/img.png');
}
.class {
/* 对 'background' 声明中第二个 url 禁用 url 处理 */
color: red;
background: url('./url/img.png'),
/* webpackIgnore: true */ url('./url/img.png');
}
/* prettier-ignore */
.class {
/* 对 'background' 声明中第二个 url 禁用 url 处理 */
color: red;
background: url("./url/img.png"),
/* webpackIgnore: true */
url("./url/img.png");
}
/* prettier-ignore */
.class {
/* 对 'background-image' 声明中第三和第六个 url 禁用 url 处理 */
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,
// 更多信息请点击这里 https://webpack.js.org/guides/asset-modules/
type: 'asset',
},
],
},
};
For production builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on.
This can be achieved by using the mini-css-extract-plugin to extract the CSS when running in production mode.
As an alternative, if seeking better development performance and css outputs that mimic production. extract-css-chunks-webpack-plugin offers a hot module reload friendly, extended version of mini-css-extract-plugin. HMR real CSS files in dev, works like mini-css in non-dev
如果项目中没有纯 CSS(没有 CSS 模块),CSS 模块和 PostCSS,则可以使用以下设置:
webpack.config.js
module.exports = {
module: {
rules: [
{
// 对于 pure CSS - /\.css$/i,
// 对于 Sass/SCSS - /\.((c|sa|sc)ss)$/i,
// 对于 Less - /\.((c|le)ss)$/i,
test: /\.((c|sa|sc)ss)$/i,
use: [
'style-loader',
{
loader: 'css-loader',
options: {
// 每一个 CSS 的 `@import` 与 CSS 模块/ICSS 都会运行 `postcss-loader`,不要忘了 `sass-loader` 将不属于 CSS 的 `@import` 编译到一个文件中
// 如果您需要在每个 CSS 的 `@import` 上运行 `sass-loader` 和 `postcss-loader`,请将其设置为 `2`。
importLoaders: 1,
},
},
{
loader: 'postcss-loader',
options: { plugins: () => [postcssPresetEnv({ stage: 0 })] },
},
// 也可能是 `less-loader`
{
loader: 'sass-loader',
},
],
},
// 对于 webpack v5
{
test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
// More information here https://webpack.js.org/guides/asset-modules/
type: 'asset',
},
],
},
};
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, '_');
},
},
},
},
],
},
};
可交互的 CSS
使其与 CSS Module
特性分离下面是有关配置的示例代码,通过为所有未匹配到 *.module.scss
命名约定文件设置 mode
选项,只允许使用 可交互的 CSS
特性(如 :import
和 :export
),而不使用其他的 CSS Module
特性。此处仅供参考,因为在 v4 之前,css-loader
默认将 ICSS
特性应用于所有文件。
同时,在本示例中,匹配到 *.module.scss
的所有文件都将被视为 CSS Modules
。
假设项目中有这样一个需求,要求 canvas 绘制使用的变量与 CSS 同步,换句话说就是 canvas 绘制使用的颜色(在 JavaScript 中设置的颜色名)与 HTML 背景(在 CSS 中通过 class 设置)相同。
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 Module
。
@import 'variables.scss';
.componentClass {
background-color: $colorBackground;
}
Component.jsx
在 JavaScript 中直接使用 CSS Module
的特性以及 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}`;
如果您还没有阅读,请花一点时间阅读我们的贡献指南。
Webpack 5 现已正式发布。请阅读我们的 发布公告。如还未准备升级,请阅读 webpack 4 文档。