如何在React项目中将node-sass替换为sass并解决编译报错问题

一、关于package-lock.json中node-sass残留声明的说明 #

你看到的package-lock.json里的node-sass条目，是sass-loader自身声明的可选对等依赖（optional peerDependency），不是项目实际安装的依赖：

• sass-loader本身同时支持node-sass和dart sass两种实现，所以会在peer依赖里把两个都列出来，并且标记为可选
• 只要你项目的package.json依赖里没有node-sass，执行npm ls node-sass返回空结果，node_modules目录下不存在node-sass文件夹，就说明node-sass已经被完全移除，lock文件里的这个声明不会对项目运行造成任何影响，不需要手动修改lock文件。

二、彻底完成依赖替换的标准操作步骤 #

如果要彻底清理所有旧依赖残留，按以下顺序执行命令：

1. 卸载所有相关依赖

npm uninstall node-sass sass sass-loader

2. 删除本地依赖文件和锁文件

• 手动删除项目根目录下的node_modules文件夹
• 删除项目根目录下的package-lock.json（使用yarn则删yarn.lock，使用pnpm则删pnpm-lock.yaml）

3. 清理npm缓存

npm cache verify

4. 重新安装适配的依赖版本
   你当前使用的sass-loader@10.1.0、webpack@5.10.1完全兼容dart sass，直接执行安装即可：

npm install sass@^1.29.0 sass-loader@10.1.0 --save-dev

安装完成后执行npm ls node-sass，确认输出没有实际安装的node-sass包即可。

三、解决expected helpers to be an object编译报错 #

这个报错和sass包替换本身没有直接关系，按以下优先级排查修复：

1. 修正webpack的sass-loader配置
   检查项目里的webpack配置，找到处理scss/sass文件的规则，删除所有强制指定node-sass作为编译实现的配置：

• 如果配置里写了implementation: require('node-sass')，直接删掉这行，sass-loader会自动识别本地安装的dart sass；或者显式改成implementation: require('sass')
• 关闭fibers相关配置，新版dart sass已经不需要fibers依赖，保留fibers配置反而容易引发版本冲突，参考正确配置：

{
  test: /\.s[ac]ss$/i,
  use: [
    'style-loader',
    'css-loader',
    {
      loader: 'sass-loader',
      options: {
        implementation: require('sass'),
        sassOptions: {
          fibers: false
        }
      }
    }
  ]
}

2. 排查不兼容webpack5的老旧依赖
   如果修正配置后还是报错，说明项目里存在依赖了不兼容版本async-helpers的老旧包：

• 执行npm ls async-helpers，找到引入这个包的上层依赖
• 把对应依赖升级到支持webpack5的版本即可，常见的触发场景是旧版的sass-resources-loader、html-webpack-plugin、自定义模板handlebars相关插件版本过低

3. 重启编译进程
   所有修改完成后，彻底关闭之前运行的webpack dev server，重新执行启动命令，不要复用之前的编译缓存。

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