首页 / three.js / API 文档

InstancedMesh

先看结论

实例化网格。同一份几何与材质重复绘制多次，每个实例只额外携带一个变换矩阵，上万个相同物体可以压到一次绘制调用。

最后验证 2026-11-03 · three.js 0.160.0 · 更新 2026-10-29 · 引用本文

new THREE.InstancedMesh(geometry, material, count)

构造参数

参数	默认	说明
`geometry`	必填	共享的几何体
`material`	必填	共享的材质
`count`	必填	实例数量，构造后不可更改

属性

属性	说明
`count`	实例数量
`instanceMatrix`	实例变换矩阵缓冲，每个实例 16 个分量，默认 `DynamicDrawUsage`
`instanceColor`	逐实例颜色缓冲，初始为 null，首次 `setColorAt` 时创建
`isInstancedMesh`	恒为 true
`castShadow` / `receiveShadow`	继承自 `Object3D`，整批实例一起开关

方法

方法	说明
`setMatrixAt(index, matrix)`	写入第 index 个实例的变换矩阵
`getMatrixAt(index, matrix)`	读出矩阵，结果写进传入的矩阵对象
`setColorAt(index, color)`	写入逐实例颜色，材质需要支持 `instanceColor`
`getColorAt(index, color)`	读取逐实例颜色
`computeBoundingBox()`	按全部实例计算整体包围盒，视锥剔除依赖它
`computeBoundingSphere()`	计算整体包围球
`dispose()`	释放实例缓冲

示例：建筑群

const geometry = new THREE.BoxGeometry(8, 1, 8);
const material = new THREE.MeshStandardMaterial({ color: 0xaeb8c2 });

const count = buildings.length;
const mesh = new THREE.InstancedMesh(geometry, material, count);

const matrix = new THREE.Matrix4();
const color = new THREE.Color();

buildings.forEach(function (b, i) {
  matrix.compose(
    new THREE.Vector3(b.x, b.height / 2, b.z),
    new THREE.Quaternion(),
    new THREE.Vector3(1, b.height, 1)
  );
  mesh.setMatrixAt(i, matrix);

  color.setHSL(0.58, 0.18, 0.55 + (b.height % 10) * 0.01);
  mesh.setColorAt(i, color);
});

mesh.instanceMatrix.needsUpdate = true;
if (mesh.instanceColor) {
  mesh.instanceColor.needsUpdate = true;
}
mesh.castShadow = true;
mesh.receiveShadow = true;
mesh.computeBoundingSphere();
scene.add(mesh);

矩阵必须先写满

构造时 instanceMatrix 全是零矩阵。没有对某个索引调用 setMatrixAt，那个实例会被缩放到 0，视觉上完全消失，而不是留在原点。数据数量少于 count 时，要么把多余实例缩放到 0，要么按实际数量构造。

与 clone 的差别

mesh.clone() 复制出的实例网格共享几何与材质，也共享实例缓冲的初始数据，但各自拥有一份缓冲对象。改克隆体的矩阵不会影响原件。需要每个实例独立可见性时，实例化网格做不到，只能拆成多个对象。

拾取

Raycaster 支持实例化网格，命中结果里的 instanceId 指出是第几个实例。修改那一个实例的颜色，需要重新调用 setColorAt 并把 instanceColor.needsUpdate 置真，无法只改 GPU 上的单个值。

实例化省的是绘制调用，不是显存。几何与材质只上传一份，但每个实例的矩阵仍占 64 字节。十万级实例约 6 MB，可接受；百万级就需要重新考虑 LOD 或分块加载。

引用本文

经纬志（2026）。《InstancedMesh》。https://www.jingweizhi.com/three/api/instanced-mesh.html（访问日期 2026-11-03）。