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)，模型就会“漂移”或“穿模”。
