pmndrs/react-three-rapier

这是什么？

核心功能

• 01以声明式的 RigidBody 和碰撞体组件接入 react-three-fiber 场景。
• 02可根据网格包围盒、球体或凸包、三角网格几何自动生成碰撞体。
• 03以 React Hook 形式提供六种关节，包括旋转、棱柱和弹簧关节。
• 04支持实例化刚体，每个实例可拥有独立碰撞体或复合形状。
• 05提供碰撞、传感器和接触力事件回调，并支持碰撞分组过滤。
• 06支持调试可视化、可配置时间步长以及世界快照序列化。

适用场景

• 为 react-three-fiber 游戏或交互场景添加掉落道具、弹跳小球等物理对象。
• 在 3D React 应用中用关节搭建布娃娃、链条、门或车轮。
• 借助实例化网格模拟成千上万个小型刚体。
• 使用传感器碰撞体检测 3D 场景中的区域或触发器。

快速上手

1. 1

   从 npm 安装该包

   npm install @react-three/rapier
2. 2

   导入 Physics 和 RigidBody，并将场景包裹在 Suspense 中的 Physics 里

使用前须知

• !v2 需要 @react-three/fiber v9 和 React v19；React v18 用户必须使用 v1 配合 fiber v8。

标签

常见问题

react-three-rapier 是什么？

将 Rapier 物理引擎接入 React Three Fiber 场景的封装库，提供刚体、碰撞体和关节组件。 react-three/rapier 将 Rapier WASM 物理引擎封装为 React 组件，使物理对象可以和网格一起声明在 react-three-fiber 场景中。Physics 组件负责创建模拟世界，RigidBody 组件把网格接入物理系统，碰撞体组件既可手动定义形状，也能根据网格几何自动生成。

react-three-rapier 可以免费使用吗？用的什么许可证？

react-three-rapier 以 MIT 许可证开源。用于商业产品前，请先确认许可证条款。

react-three-rapier 还在维护吗？

活跃维护中。react-three-rapier 最近一次提交是在 2026年10月12日。

react-three-rapier 适合用来做什么？

为 react-three-fiber 游戏或交互场景添加掉落道具、弹跳小球等物理对象。 在 3D React 应用中用关节搭建布娃娃、链条、门或车轮。 借助实例化网格模拟成千上万个小型刚体。 使用传感器碰撞体检测 3D 场景中的区域或触发器。

react-three-rapier 怎么安装和运行？

从 npm 安装该包: npm install @react-three/rapier 导入 Physics 和 RigidBody，并将场景包裹在 Suspense 中的 Physics 里

在哪里获取 react-three-rapier？

源代码和安装说明在 GitHub 上：https://github.com/pmndrs/react-three-rapier