Three.js配置OrbitControls的min/maxDistance后页面空白问题

取消注释后页面空白是JavaScript运行抛出未捕获错误，导致整个脚本执行中断，渲染逻辑完全没跑起来，绝大多数情况是以下两个原因：

• 变量未声明：你写的controls = new THREE.OrbitControls(...)没有用const/let提前声明controls变量，在现代浏览器默认运行环境（尤其是使用script type="module"时）会直接抛出ReferenceError，脚本直接终止运行。
• OrbitControls引用错误：近年发布的Three.js新版本已经不再把OrbitControls挂载到THREE全局对象下，直接调用new THREE.OrbitControls()会抛出「不是构造函数」的错误，同样会中断脚本执行。

1. 先匹配OrbitControls的引入方式：
   • 如果是用普通script标签引入CDN旧版本，确保OrbitControls的script标签放在Three.js标签之后，且两者版本号完全一致
   • 如果是用ES Module方式开发（官方当前推荐方式），需要单独导入OrbitControls，不要从THREE全局对象上取值
2. 初始化OrbitControls前必须先声明controls变量，不要直接给未声明的变量赋值
3. 配置完缩放距离限制后，保留动画循环里的controls.update()调用即可

全局脚本引入场景（对应你原有代码结构） #

//scene
const scene = new THREE.Scene();
//camera
const camera = new THREE.PerspectiveCamera( 75, window.innerWidth / window.innerHeight, 0.1, 1000 );

//renderer
const renderer = new THREE.WebGLRenderer();
renderer.setSize( window.innerWidth, window.innerHeight );
document.body.appendChild( renderer.domElement );


const geometry = new THREE.SphereGeometry(10,10,10)
const material = new THREE.MeshNormalMaterial({wireframe:true})
const sphere = new THREE.Mesh(geometry,material)
scene.add(sphere)

const geometry2 = new THREE.SphereGeometry(10,10,10)
const material2 = new THREE.MeshNormalMaterial({wireframe:true})
const sphere2 = new THREE.Mesh(geometry2,material2)
sphere2.position.x = 40
scene.add(sphere2)

const geometry3 = new THREE.SphereGeometry(10,10,10)
const material3 = new THREE.MeshNormalMaterial({wireframe:true})
const sphere3 = new THREE.Mesh(geometry3,material3)
sphere3.position.x = -40
scene.add(sphere3)

camera.position.z = 70        

// 提前声明controls变量，全局引入场景下保留THREE.前缀
const controls = new THREE.OrbitControls(camera,renderer.domElement)
controls.minDistance = 1
controls.maxDistance = 1000


const animate = () => {
    requestAnimationFrame(animate)
    
    sphere.rotation.x += 0.02
    sphere.rotation.y += 0.02

    sphere2.rotation.x += 0.02
    sphere2.rotation.y += 0.02

    sphere3.rotation.x += 0.02
    sphere3.rotation.y += 0.02
    controls.update()

    renderer.render(scene,camera)
}

animate()

ES Module开发场景 #

只需要调整头部引入和controls初始化逻辑，其余场景代码和上面一致：

import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

// 初始化controls时不需要加THREE.前缀
const controls = new OrbitControls(camera, renderer.domElement)

调试这类白屏问题直接打开浏览器F12开发者工具的Console面板，红色报错信息会直接定位具体错误点，不需要盲目排查。

内容的提问来源于stack exchange，提问作者Paulinus