使用@react-google-maps/api构建Next.js应用时构建失败求助

错误原因 #

该问题源于项目中存在多版本@types/react类型定义冲突：hoist-non-react-statics依赖的@types/react版本与项目本身的React类型版本不匹配，导致ReactNode类型无法兼容，进而触发GoogleMap组件的JSX类型校验失败。

解决方案 #

• 强制统一@types/react版本
  针对不同包管理器，通过锁定@types/react版本消除冲突：

  • Yarn用户：在package.json中添加resolutions字段后重新安装依赖

    "resolutions": {
      "@types/react": "^18.2.0"
    }
    

    执行命令：yarn install
  • NPM用户：先安装依赖强制解析工具，再锁定版本

    npm install -D npm-force-resolutions
    

    在package.json的scripts和resolutions中添加配置：

    "scripts": {
      "preinstall": "npx npm-force-resolutions"
    },
    "resolutions": {
      "@types/react": "^18.2.0"
    }
    

    执行命令：npm install

• 更新@react-google-maps/api到最新版本
  新版本通常会修复依赖类型兼容问题，执行更新命令：

  # NPM
  npm update @react-google-maps/api
  # Yarn
  yarn upgrade @react-google-maps/api
  

• 调整组件空状态返回值
  将组件中isLoaded为false时的空Fragment返回改为明确值（如null或加载占位），避免类型检查异常：

  return isLoaded ? (
    <div className={style["map-tab"]}>
      {/* 原组件内容 */}
    </div>
  ) : (
    // 可选：替换为加载占位组件
    // <div className={style["map-loading"]}>地图加载中...</div>
    null
  );
  

• 校验tsconfig.json配置
  确保tsconfig.json中仅引入必要的类型定义，避免重复冲突：

  {
    "compilerOptions": {
      "types": ["react", "react-dom", "google.maps"]
    }
  }
  

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