Webpackcss-loader配置全解析

本文深入剖析了 Webpack 中 css-loader 的核心配置要点与常见陷阱：从 @import/url() 路径解析失效的根源及解决方案（需显式启用 import/url 选项或借助 postcss-import），到 CSS Modules 的精细化控制（modules 配置差异、TS 项目必备的 exportLocalsConvention 设置），再到它与 style-loader 和 mini-css-extract-plugin 的职责边界与协作规范（css-loader 只解析不注入/抽离），最后揭秘 SourceMap 定位失准的本质——必须全链路（预处理器 → css-loader → postcss-loader → 输出插件）协同开启且配置一致。无论你是调试样式引入失败、遭遇 TS 类型报错，还是被热更新异常或生产环境 CSS 阻塞困扰，这篇文章都直击痛点，提供可立即落地的实操指南。

css-loader 为什么解析不了 @import 或 url()？

默认情况下 css-loader 不处理 @import 和 url() 中的路径，它只做 CSS 模块化和局部作用域转换。真正解析这些语句的是 resolve-url-loader 或更常见的——靠 postcss-loader + postcss-import，或者干脆交给 css-loader 自己的 import 和 url 选项。

实操建议：

• 检查是否启用了 import 和 url 选项（v6+ 默认开启，但 v5 及以前默认 false）
• 若用相对路径如 @import "./vars.css";，确保路径相对于当前 CSS 文件，不是 Webpack 入口
• 遇到 Module not found: Error: Can't resolve './xxx.css'，大概率是路径没对上，别急着加 alias，先用 resolve.alias 看是否影响了 CSS 解析上下文

css-loader 的 modules 配置怎么选：true、'local' 还是对象？

modules 控制 CSS Modules 行为，不同写法差异很大，不是“开了就自动局部作用域”。

常见错误现象：className 没变哈希、样式全局泄漏、TS 类型报错 Property 'xxx' does not exist on type。

实操建议：

• modules: true → 等价于 modules: { mode: 'local' }，适用于普通项目
• 想局部作用域但保留部分全局类（比如第三方 UI 库），用 modules: { mode: 'pure' } 或配合 auto 正则匹配文件名
• TS 项目必须配 modules: { exportLocalsConvention: 'camelCaseOnly' }，否则 styles.redButton 会变成 styles['red-button']
• 别在同一个项目里混用 modules: true 和 modules: { ... }，Webpack 不会合并配置，后写的会覆盖前的

css-loader 和 style-loader / mini-css-extract-plugin 怎么协作不翻车？

css-loader 只负责解析 CSS 文本和依赖，它不插入 DOM，也不输出文件。谁干这事？style-loader 把 CSS 注入