使用gulp serve测试SPFx Web Part时遇SPLoaderError加载失败求助

问题概述 #

使用gulp serve在workbench.aspx测试SharePoint Framework（SPFx）Web Part时，触发SPLoader错误：无法找到组件ID为aa0a46ec-1505-43cd-a44a-93f3a5aa460a（对应React）的17.0.2版本清单。已尝试升级React到17.0.2、删除node_modules和package-lock.json重新安装，但问题未解决。

解决方案 #

1. 精确锁定React版本 #

修改package.json，将React相关依赖的版本从带^的兼容范围改为精确的17.0.2，避免npm自动拉取其他版本：

"dependencies": {
  // ...其他依赖
  "react": "17.0.2",
  "react-dom": "17.0.2"
},
"devDependencies": {
  // ...其他依赖
  "@types/react": "17.0.2",
  "@types/react-dom": "17.0.2"
}

2. 清理重复依赖 #

执行npm去重命令，合并相同依赖的不同版本实例：

npm dedupe

3. 彻底清理SPFx构建缓存 #

除了node_modules，还需清理SPFx的构建输出和缓存文件：

• 执行SPFx官方清理命令：

  gulp clean
  

• 手动删除项目根目录下的temp和lib文件夹

4. 强制统一第三方依赖的React版本（若存在冲突） #

如果第三方依赖（如@coveo/headless、@mui/material）要求不同的React版本，可在package.json中添加overrides字段（npm 8.3+支持），强制所有依赖使用指定的React版本：

"overrides": {
  "react": "17.0.2",
  "react-dom": "17.0.2"
}

5. 重新构建并启动服务 #

完成上述步骤后，重新安装依赖并构建项目：

npm install
gulp bundle --ship
gulp serve

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