react-map-gl编译报错Module not found：无法解析gl-matrix/mat4问题求助

原始报错信息：

Failed to compile
./node_modules/@math.gl/web-mercator/dist/esm/web-mercator-viewport.js
Module not found: Can't resolve 'gl-matrix/mat4' in 'D:\Projects\react-app\frontend\node_modules\@math.gl\web-mercator\dist\esm'

问题根因 #

该报错是@math.gl/web-mercator（react-map-gl的依赖包）缺失了gl-matrix依赖，或者依赖版本不匹配导致的，属于包依赖声明遗漏的共性问题，和本地项目配置无关。

可执行解决步骤 #

• 方案1：手动安装匹配版本的gl-matrix依赖
  执行对应包管理工具的安装命令即可：

  # npm 用户
  npm install gl-matrix@^3.4.3
  # yarn 用户
  yarn add gl-matrix@^3.4.3
  # pnpm 用户
  pnpm add gl-matrix@^3.4.3
  

  安装完成后重新启动项目即可正常编译。

• 方案2：配置依赖版本强制覆盖（多版本冲突时使用）
  如果安装后依然报错，说明存在依赖版本冲突，可在package.json中添加强制版本规则：

  // npm 用户添加如下配置
  "overrides": {
    "@math.gl/web-mercator": {
      "gl-matrix": "^3.4.3"
    }
  }
  

  // yarn 用户添加如下配置
  "resolutions": {
    "@math.gl/web-mercator/gl-matrix": "^3.4.3"
  }
  

  配置完成后重新执行依赖安装命令，再启动项目即可。

• 方案3：清理缓存重装全部依赖
  如果上述方案都不生效，执行如下操作完全重置依赖：

  1. 删除项目根目录下的node_modules文件夹
  2. 删除项目根目录下的锁文件：package-lock.json/yarn.lock/pnpm-lock.yaml
  3. 执行缓存清理命令：npm cache clean --force
  4. 重新执行npm install/yarn install/pnpm install安装全部依赖

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