Gatsby中CSS Modules改为SCSS格式后出现Webpack错误的问题咨询

这个构建报错本质是webpack加载链路中，mini-css-extract-plugin 接收到的css-loader modules 配置格式不符合要求，和你写的组件逻辑、SCSS样式内容本身没有关联。

• 全局SCSS运行正常的原因：不带模块标识的全局SCSS文件走普通样式加载规则，不需要启用CSS Modules的类名隔离逻辑，因此不会触发该配置校验错误。
• 模块化SCSS报错的原因：Gatsby 内置的webpack规则默认只会为匹配*.module.css命名的文件，自动注入格式合规的CSS Modules配置。当你把模块文件后缀切换为*.module.scss时，如果gatsby-plugin-sass的默认配置没有正确对齐这套内置规则，就会让mini-css-extract-plugin读到非对象结构的modules配置值，最终抛出options.modules should be object的错误。

• 调整gatsby-plugin-sass的引入形式，替换原先纯字符串的引入逻辑，在插件配置中显式声明符合格式要求的CSS Modules参数，满足各loader的校验规则：

  module.exports = {
    plugins: [
      "gatsby-plugin-react-helmet",
      {
        resolve: `gatsby-plugin-sass`,
        options: {
          cssLoaderOptions: {
            modules: {
              localIdentName: "[name]__[local]___[hash:base64:5]",
            },
          },
        },
      },
    ],
  };
  

• 排查依赖版本冲突：如果修改配置后报错仍然存在，说明本地依赖存在版本不一致问题——比如项目中重复安装了不同版本的mini-css-extract-plugin，或是全局/本地安装的sass编译包和插件要求的版本不兼容。这种情况可以删除本地node_modules目录和依赖锁文件（package-lock.json / yarn.lock）后重新安装依赖，确保Gatsby核心和插件关联的loader版本完全对齐。
• 确认文件命名规范：所有需要启用CSS Modules的SCSS文件，必须严格使用.module.scss作为后缀，不要用普通.scss后缀命名需要做样式隔离的文件，否则Gatsby不会自动匹配对应的CSS Modules加载规则，也会触发同类报错。

内容的提问来源于stack exchange，提问作者Piotr A