SPFx安装@pnp/spfx-property-controls依赖报错及组件缺失问题求助

问题背景 #

• 环境信息：Windows平台，nodeJS v16.18.1，npm 8.19.2，gulp CLI v2.3.0（本地v4.0.2），yeoman 4.3.1，@microsoft/generator-sharepoint@1.16.1
• 核心问题：
  1. 执行npm install @pnp/spfx-property-controls --save --save-exact后，出现react-ace@5.8.0与react/react-dom@17.0.1的peer dependency冲突警告
  2. 按教程修改项目后gulp serve执行成功，但工作台报错：组件ID为0d910c1c-13b9-4e1c-9aa4-b008c5e42d7d（对应React组件）的17.0.2版本清单未找到，项目依赖中同时存在React 17.0.1和17.0.2两个版本

解决步骤 #

1. 统一React版本，强制使用17.0.1 #

• 打开项目根目录的package.json，确保dependencies中react和react-dom的版本明确锁定为17.0.1：

  "dependencies": {
    "react": "17.0.1",
    "react-dom": "17.0.1",
    // 其他项目依赖...
  }
  

• 添加resolutions字段到package.json，强制所有子依赖使用指定的React版本（npm v7+支持）：

  "resolutions": {
    "react": "17.0.1",
    "react-dom": "17.0.1"
  }
  

• 执行npm install重新安装依赖，确保整个依赖树统一使用React 17.0.1

2. 消除react-ace的peer依赖警告 #

• 若警告不影响功能可直接忽略；若需彻底消除，使用npm的legacy-peer-deps参数重新安装PnP控件：

  npm uninstall @pnp/spfx-property-controls
  npm install @pnp/spfx-property-controls --save --save-exact --legacy-peer-deps
  

• --legacy-peer-deps会采用npm v6的依赖解析逻辑，忽略peer依赖冲突，适配SPFx这类有固定框架依赖的场景

3. 清理缓存并重新构建项目 #

• 删除本地依赖缓存和锁定文件：

  rm -rf node_modules package-lock.json
  

• 重新安装依赖并构建：

  npm install
  gulp clean && gulp build && gulp serve
  

4. 验证SPFx配置一致性 #

• 检查config/config.json中的externals配置，确保react/react-dom的CDN路径版本与项目依赖一致：

  "externals": {
    "react": {
      "path": "https://unpkg.com/react@17.0.1/umd/react.production.min.js",
      "globalName": "React"
    },
    "react-dom": {
      "path": "https://unpkg.com/react-dom@17.0.1/umd/react-dom.production.min.js",
      "globalName": "ReactDOM"
    }
  }
  

• 确认sharepoint/assets/elements.xml中引用的React组件版本与实际依赖匹配

内容的提问来源于stack exchange，提问作者B-and-P