react-app-rewired项目SCSS文件导入失败问题求助

问题背景 #

接手两年未维护的 react-app-rewired 项目，替换废弃的 node-sass 为 sass 后安装成功，但 yarn start 时出现大量 SCSS 导入错误，仅 Intel Mac 可正常运行，Windows/M1 Mac 均失败。

修复步骤 #

1. 对齐依赖版本并清理残留 #

• 完全移除 node-sass 相关依赖，清理缓存和依赖目录：

  yarn remove node-sass
  rm -rf node_modules
  rm yarn.lock
  

• 安装适配 Node 12.22.5 的依赖版本，避免兼容性冲突：

  yarn add sass@1.32.13 sass-loader@10.2.0 react-app-rewired@2.2.1 customize-cra@1.0.0 --dev
  

2. 配置 config-overrides.js 支持 sass #

修改你的 config-overrides.js，新增 sass 加载器配置，确保 webpack 正确识别 dart-sass：

const { override, addBabelPlugin, addWebpackPlugin, addWebpackModuleRule, addSassLoader } = require('customize-cra');
const CopyWebpackPlugin = require('copy-webpack-plugin');
const { DumpMetaPlugin } = require('dumpmeta-webpack-plugin');
const workboxPlugin = require('workbox-webpack-plugin');
const path = require('path'); // 新增引入path模块

// 保留原有插件和规则代码
const addEnvToManifest = new CopyWebpackPlugin([
  {
    from: 'public/manifest.json',
    to: 'manifest.json',
    transform(content, path) {
      const manifest = JSON.parse(content.toString());
      const { REACT_APP_ENVIRONMENT } = process.env;
      if (!REACT_APP_ENVIRONMENT.includes('master')) {
        manifest.name = `${REACT_APP_ENVIRONMENT}-${manifest.name}`;
        manifest.short_name = REACT_APP_ENVIRONMENT;
      }

      return JSON.stringify(manifest, null, 2);
    },
  },
]);

const copyWebComponents = new CopyWebpackPlugin([
  {
    context: 'node_modules/@webcomponents/webcomponentsjs',
    from: '**/*.js',
    to: 'webcomponents',
  },
]);

const generateVersionFile = new DumpMetaPlugin({
  filename: 'build/version.json',
  prepare: stats => ({
    hash: stats.hash,
    buildDate: new Date(),
    env: process.env.REACT_APP_ENVIRONMENT,
  }),
});

const imageOptimizationRule = {
  test: /\.(gif|png|jpe?g|svg)$/i,
  use: [
    'file-loader',
    {
      loader: 'image-webpack-loader',
      options: {
        mozjpeg: {
          progressive: true,
          quality: 100,
        },
        pngquant: {
          quality: [0.65, 0.90],
          speed: 4,
        },
        gifsicle: {
          interlaced: false,
        },
      },
    },
  ],
};

const workbox = new workboxPlugin.InjectManifest({
  swSrc: './src/sw.js',
  swDest: 'sw.js',
  maximumFileSizeToCacheInBytes: 100 * 1024 * 1024,
});

module.exports = override(
  addWebpackModuleRule(imageOptimizationRule),
  addWebpackPlugin(copyWebComponents),
  addBabelPlugin('import-graphql'),
  addWebpackPlugin(generateVersionFile),
  addWebpackPlugin(addEnvToManifest),
  addWebpackPlugin(workbox),
  // 新增sass加载器配置
  addSassLoader({
    implementation: require('sass'),
    sassOptions: {
      // 若项目有全局样式目录，添加includePaths确保导入路径正确
      includePaths: [path.resolve(__dirname, 'src/styles')]
    }
  })
);

3. 修复跨平台 SCSS 导入路径问题 #

• 统一 SCSS 文件中的导入路径写法，全部使用正斜杠 /，避免 Windows 反斜杠 \：

  // 正确写法
  @import './components/Button/styles.scss';
  // 错误写法（需修改）
  @import '.\components\Button\styles.scss';
  

• 移除导入 node_modules 样式时的 ~ 前缀（新版 sass-loader 无需此前缀）：

  // 正确写法
  @import 'bootstrap/scss/bootstrap';
  // 旧写法（需修改）
  @import '~bootstrap/scss/bootstrap';
  

4. 处理 M1 Mac 架构兼容问题 #

• 用 Rosetta 2 打开终端（右键终端 → 显示简介 → 勾选「使用 Rosetta 打开」），重新执行 yarn install 和 yarn start
• 若仍有问题，强制以 x86_64 架构安装依赖：

  arch -x86_64 yarn install
  

5. 清理缓存并重新构建 #

yarn cache clean
yarn start --reset-cache

额外排查点 #

• 对比搭档的 yarn.lock 文件，检查依赖版本差异，可直接复制搭档的 lock 文件后重新安装（注意跨平台二进制依赖差异）
• 检查项目中是否存在硬编码的绝对路径，替换为相对路径或使用 path.resolve 动态生成路径

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