首页 / three.js / API 文档
BoxGeometry
先看结论
立方体几何。由宽、高、深三个尺寸生成，是建筑体块、设备外壳、 占位模型最常用的基础几何。
new THREE.BoxGeometry(width, height, depth, widthSegments, heightSegments, depthSegments)
构造参数
| 参数 | 默认 | 说明 |
|---|---|---|
width | 1 | X 方向尺寸 |
height | 1 | Y 方向尺寸 |
depth | 1 | Z 方向尺寸 |
widthSegments | 1 | X 方向分段数，最小 1 |
heightSegments | 1 | Y 方向分段数，最小 1 |
depthSegments | 1 | Z 方向分段数，最小 1 |
生成的属性
| 属性 | 说明 |
|---|---|
position | 顶点位置，每面独立顶点，便于法线与 UV 分离 |
normal | 面法线，六个方向各自朝外 |
uv | 每面覆盖完整的 0 到 1 UV 区间 |
groups | 六个材质分组，顺序为右、左、上、下、前、后 |
index | 三角形索引 |
示例：带屋顶的建筑体块
const geometry = new THREE.BoxGeometry(16, 36, 12);
const wall = new THREE.MeshStandardMaterial({ color: 0xa8b2bd, roughness: 0.85 });
const roof = new THREE.MeshStandardMaterial({ color: 0x3f4a55, roughness: 0.6 });
// 六个面分别指定材质，未列出的位置沿用同一个
const mesh = new THREE.Mesh(geometry, [wall, wall, roof, wall, wall, wall]);
mesh.position.set(80, 18, -20);
mesh.castShadow = true;
mesh.receiveShadow = true;
scene.add(mesh);分段数的用途
分段数大于 1 时，每个面被切成多块格子。单纯做直角体块不需要分段， 增加只会提高顶点数。需要以下效果时才调高：
- 顶点位移或波浪动画：顶面需要足够多的顶点才能起伏。
- 顶点色渐变：分段越多，颜色过渡越平滑。
- 顶点着色器里按高度变形：分段决定了变形是否连续。
中心在几何中心
BoxGeometry 的原点在体块中心，不是底面。
想让建筑坐在地面上，位置高度要设为 height / 2，
否则会有一半埋进地里。需要原点在底面时，
创建后调用 geometry.translate(0, height / 2, 0)。
体块数量多时改用实例化。上千个尺寸相近的建筑用
InstancedMesh 共享一份 BoxGeometry，
通过矩阵控制每个实例的尺寸，比逐个创建网格省一个数量级的绘制调用。
经纬志（2026）。《BoxGeometry》。https://www.jingweizhi.com/three/api/box-geometry.html（访问日期 2026-11-03）。