部署React项目到GitHub Pages时出现Module not found报错咨询

你遇到的报错是两个独立问题叠加导致的：

1. 直接触发构建失败的是依赖缺失：你安装的@fortawesome/react-fontawesome@0.1.18必须搭配同系列的@fortawesome/fontawesome-svg-core包才能运行，这个包是作为peer依赖要求手动安装的，但你的package.json里没有声明这个依赖。本地start脚本能正常跑是dev模式的模块解析有缓存和容错机制，生产构建是严格静态解析，缺包直接终止编译。
2. 上游依赖冲突本质是版本不兼容：你用的react-leaflet@3.2.5最高只支持React 17，peer依赖明确要求react@^17.0.1，和你项目里安装的React 18.0.0版本不匹配。之前加--legacy-peer-deps参数只是跳过了npm的依赖合法性校验，并没有真正解决版本兼容问题，还会导致安装过程漏装不符合校验规则的嵌套依赖，进一步放大了缺包问题。

按顺序操作即可：

• 先清理损坏的依赖环境：删除项目根目录下的node_modules文件夹和package-lock.json文件，后续安装依赖不要加--legacy-peer-deps或--force这类跳过校验的参数，避免再次出现依赖缺失或兼容问题。
• 补装缺失的FontAwesome核心包，执行命令：
  npm i @fortawesome/fontawesome-svg-core@^6.1.1
  安装时指定版本和你已装的@fortawesome/free-brands-svg-icons、@fortawesome/free-solid-svg-icons保持一致，避免同系列包版本不匹配。
• 解决React和react-leaflet的版本冲突，二选一即可：
  • 推荐方案：升级react-leaflet到适配React 18的v4版本，执行npm i react-leaflet@^4.0.0，该版本已完全适配React 18的渲染API，不会再触发peer依赖报错。
  • 备选方案：如果暂时不想升级react-leaflet，就把项目中react、react-dom的版本降到17.0.2，对应修改package.json中两个包的版本号为"react": "^17.0.2", "react-dom": "^17.0.2"即可，该方案后续升级React大版本时需要重新调整依赖，优先选升级方案。
• 所有依赖版本调整完成后，执行npm install重新安装全量依赖，先本地跑npm run build验证构建流程，确认构建无报错后再执行npm run deploy部署到GitHub Pages即可。

*注意：--legacy-peer-deps只是临时绕过校验的手段，不能解决实际的版本兼容问题，长期使用会导致生产构建、线上运行时出现无明确日志的异常，遇到依赖冲突优先调整包版本到兼容区间，不要靠强制参数跳过校验。

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