Webpack 5 中 SCSS 模块导入问题的解决方案

问题背景

在将项目从 Webpack 4 升级到 Webpack 5 后，许多开发者遇到了 SCSS 模块导入失效的问题。具体表现为当使用 import styles from './BlockAccess.module.scss' 语法导入 SCSS 文件时，styles 对象变成了 undefined。

问题根源

这个问题源于 Webpack 5 和 css-loader 7.0.0 及以上版本对模块导出的处理方式发生了变化。在较新版本中，CSS/SCSS 模块的局部样式默认作为命名导出(named exports)而非默认导出(default export)。

解决方案

方法一：修改导入语法

最简单的解决方案是修改导入语法，使用命名导入方式：

import * as styles from './BlockAccess.module.scss';

这种语法能够正确捕获 SCSS 模块中的所有命名导出样式。

方法二：配置 css-loader

如果你希望保持原有的导入语法，可以在 webpack 配置中修改 css-loader 的选项：

{
  loader: require.resolve('css-loader'),
  options: {
    modules: {
      mode: 'local',
      exportLocalsConvention: 'camelCaseOnly',
      namedExport: false // 保持旧版行为
    }
  }
}

技术原理

在 Webpack 5 生态中，css-loader 7+ 版本为了更好的支持 ES 模块规范，改变了导出方式：

1. 旧版本(6及以下)会将所有样式作为默认导出
2. 新版本(7+)将样式类名作为命名导出，更符合 ES 模块规范

这种变化带来了几个优势：

• 更好的 tree-shaking 支持
• 更清晰的模块导出结构
• 与 JavaScript 模块系统保持一致

最佳实践建议

1. 统一导入方式：建议项目统一采用 import * as styles 语法，这是未来的标准方式
2. 类型支持：如果使用 TypeScript，确保有正确的类型定义文件(.d.ts)支持 SCSS 模块
3. 逐步迁移：大型项目可以先用方案二保持兼容，再逐步迁移到新语法

总结

Webpack 5 和 css-loader 7+ 对 CSS/SCSS 模块的导出方式进行了现代化改造，虽然这带来了短暂的兼容性问题，但从长远看有利于项目的模块化发展。理解这一变化背后的设计理念，有助于开发者更好地适应现代前端构建工具的发展趋势。