Three.js 中 Raycaster 是最常用且可靠的碰撞检测方案，通过射线与几何体相交实现点击、视线等交互响应，需正确收集可交互 Mesh 并优化性能。

Three.js 中 Raycaster 是最常用且可靠的碰撞检测方案

原生 HTML5 不提供 3D 碰撞检测能力，所谓“HTML5 建模”实际依赖 WebGL 库（如 Three.js）。真正在运行时做模型间碰撞判断的，几乎都用 Raycaster 模拟射线与几何体相交——它不计算物理碰撞，但能精准响应点击、视线、投掷等交互场景。

常见错误是直接对 Mesh 对象调用 intersects，但 Three.js 的 Raycaster 必须配合场景中真实渲染的 Object3D 子集（通常是 mesh 或 group）才能工作。

• 必须在渲染循环（requestAnimationFrame）中更新 Raycaster.setFromCamera，否则坐标系错乱
• 被检测对象需启用 castShadow = true 和 receiveShadow = true（非必需，但影响光照反馈）
• 若模型由多个子 Mesh 组成（如 GLTF 导入），需递归遍历 scene.traverse 收集所有可交互 Mesh

GLTF 模型加载后如何正确设置可碰撞对象

用 GLTFLoader 加载的模型默认是 Group，其子节点可能是嵌套多层的 Mesh。直接把整个 Group 传给 Raycaster.intersectObjects 会失败，因为 Raycaster 只检查 Mesh、Line、Points 这类可渲染对象。

正确做法是提取所有叶子级 Mesh 并打上自定义标记，方便后续过滤：

loader.load('model.glb', (gltf) => {
  const meshes = [];
  gltf.scene.traverse((obj) => {
    if (obj.isMesh) {
      obj.userData.collidable = true; // 标记为可碰撞
      obj.userData.id = 'door_01';   // 可选：绑定业务 ID
      meshes.push(obj);
    }
  });
  scene.add(gltf.scene);
  collidableMeshes = meshes; // 全局或闭包保存
});

注意：不要修改 obj.material 的 transparent 或 opacity 后忘记设 depthWrite: false，否则射线可能穿模。

Raycaster.intersectObjects 性能瓶颈与优化技巧

每帧都对上百个 Mesh 调用 intersectObjects 会导致卡顿。Three.js 官方建议控制在 50 个以内参与检测的对象。

• 用空间划分：只检测摄像机视锥体内的对象（frustum.containsPoint(mesh.position)）
• 对静态模型预生成 BufferGeometry 的 bbox（包围盒），先做粗筛：bbox.intersectsSphere(ray.origin, ray.far)
• 避免每帧重建 Raycaster 实例，复用单例并仅调用 .set() 和 .intersectObjects()
• 移动端慎用 raycaster.params.Line.threshold，部分 Android WebView 不支持

两个 3D 模型之间是否“真正相碰”？别信 distanceTo

新手常误用 mesh1.position.distanceTo(mesh2.position) 判断碰撞——这只能测中心点距离，对长条形、旋转后模型完全失效。

真正需要实体级碰撞（如门碰到人、箱子堆叠），必须引入物理引擎，例如：

• cannon-es：轻量、TypeScript 原生，适合简单刚体
• ammo.js：完整 Bullet 物理移植，性能高但体积大（~3MB）
• rapier：Rust 编译，API 清晰，WASM 加速，推荐新项目

即使引入物理引擎，Three.js 渲染层和物理层的坐标、旋转仍需手动同步。漏掉 body.quaternion.copy(mesh.quaternion) 或 mesh.position.copy(body.position)，模型就会“漂移”或“穿模”。