本教程旨在解决 three.js项目开发中常见的画布不渲染问题，即使控制台无报错。核心原因在于初始化函数（如 `main()`）虽已定义，但未被显式调用执行。文章将通过代码示例详细阐述这一易被忽视的细节，并提供正确的代码结构，确保 three.js场景能够顺利呈现在网页上，帮助开发者避免此类基础错误。
在 Three.js 开发中，开发者有时会遇到这样的困惑：按照官方示例编写了代码，浏览器 控制台也没有任何错误提示，但页面上却始终是一片空白，Three.js 画布（canvas）未能如预期般渲染出任何内容。这通常发生在初始化阶段，且往往源于一个看似简单却极易被忽视的编程习惯。
核心问题：函数定义与执行
造成 Three.js 画布不渲染而无报错的最常见原因之一，是定义了初始化场景的函数（例如 m ain()），但却没有在脚本中显式地调用它。函数仅仅被定义，其内部的逻辑并不会自动执行。这就像你写好了一份菜谱，但没有实际去烹饪一样，菜肴自然不会出现。
考虑以下示例代码片段，它展示了一个典型的 Three.js 场景初始化结构：
<head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Three.js Canvas Demo</title> </head> <body> <canvas id="c"></canvas> <script type="module"> import * as THREE from "https://cdn.skypack.dev/three"; import {OrbitControls} from "https://cdn.skypack.dev/three/examples/jsm/controls/OrbitControls.js"; function main() { const canvas = document.getElementById('c'); const renderer = new THREE.webglRenderer({canvas}); const fov = 75; const aspect = 2; // the canvas default const near = 0.1; const far = 5; const camera = new THREE.PerspectiveCamera(fov, aspect, near, far); camera.position.z = 2; const scene = new THREE.Scene(); const boxWidth = 1; const boxHeight = 1; const boxDepth = 1; const geometry = new THREE.BoxGeometry(boxWidth, boxHeight, boxDepth); const material = new THREE.MeshBasicMaterial({color: 0x44aa88}); // 绿色方块 const cube = new THREE.Mesh(geometry, material); scene.add(cube); renderer.setSize(window.innerWidth, window.innerHeight); renderer.render(scene, camera); } // 这里缺少了对 main() 函数的调用 </script> </body> </html>在这段代码中，main()函数包含了所有设置 Three.js 场景、相机、渲染器、几何体和材质的逻辑，并且最后调用了 renderer.render(scene, camera)来渲染场景。然而，由于 main()函数本身从未被调用，其内部的所有指令都未能执行，导致画布保持空白。
解决方案：显式调用初始化函数
解决这个问题的关键在于，在定义完初始化函数后，显式地调用它。对于上述示例，只需在 <script> 标签的末尾添加一行代码即可：
// …… (main 函数定义结束） main(); // 显式调用 main 函数通过这一简单的调用，main()函数中的所有 Three.js 初始化和渲染逻辑将被执行，你的场景便会呈现在画布上。
完整的修正代码示例
以下是经过修正的完整 html 文件，包含了对 main() 函数的正确调用：
<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Three.js Canvas 渲染示例 </title> <style> body {margin: 0; overflow: hidden;} /* 移除默认边距和滚动条 */ canvas {display: block;} /* 确保 canvas 占满空间 */ </style> </head> <body> <canvas id="c"></canvas> <script type="module"> import * as THREE from "https://cdn.skypack.dev/three"; import {OrbitControls} from "https://cdn.skypack.dev/three/examples/jsm/controls/OrbitControls.js"; function main() { const canvas = document.getElementById('c'); // 确保 canvas 存在 if (!canvas) {console.error("Canvas element with ID 'c' not found!"); return; } const renderer = new THREE.WebGLRenderer({canvas}); renderer.setSize(window.innerWidth, window.innerHeight); // 设置渲染器尺寸 const fov = 75; const aspect = window.innerWidth / window.innerHeight; // 根据窗口尺寸动态计算 aspect const near = 0.1; const far = 5; const camera = new THREE.PerspectiveCamera(fov, aspect, near, far); camera.position.z = 2; // 相机后移，以便看到物体 const scene = new THREE.Scene(); scene.background = new THREE.Color(0xAAAAAA); // 设置场景背景色，方便观察 // 添加一个简单的立方体 const boxWidth = 1; const boxHeight = 1; const boxDepth = 1; const geometry = new THREE.BoxGeometry(boxWidth, boxHeight, boxDepth); const material = new THREE.MeshBasicMaterial({color: 0x44aa88}); // 绿色方块 const cube = new THREE.Mesh(geometry, material); scene.add(cube); // 如果需要交互，可以添加轨道控制器 // const controls = new OrbitControls(camera, canvas); // controls.enableDamping = true; // 启用阻尼，使动画更平滑 // controls.dampingFactor = 0.25; // 处理窗口大小变化 function onWindowResize() { camera.aspect = window.innerWidth / window.innerHeight; camera.updateProjectionMatrix(); renderer.setSize(window.innerWidth, window.innerHeight); // 如果有动画 循环 ，还需要在动画循环中调用 render // render(); // 如果是静态场景，只需在 resize 后重新渲染} window.addEventListener('resize', onWindowResize); // 渲染场景 renderer.render(scene, camera); // 对于动态场景，通常需要一个动画循环 // function animate() { // requestAnimationFrame(animate); // // cube.rotation.x += 0.01; // // cube.rotation.y += 0.01; // // controls.update(); // 如果使用 OrbitControls，需要更新 // renderer.render(scene, camera); // } // animate();} // 确保dom 加载完成后再调用 main 函数 document.addEventListener('DOMContentLoaded', main); // 或者使用 window.onload = main; </script> </body> </html>注意事项与最佳实践
- DOM 加载完成 事件 ： 建议将 main() 函数的调用包裹在 DOMContentLoaded 事件监听器中，或使用 window.onload。这确保了在脚本执行时，HTML 文档（包括 <canvas> 元素）已经完全加载并解析，避免出现 document.getElementById(‘c’) 返回 NULL 的情况。在上面的修正代码中，我们使用了 document.addEventListener(‘DOMContentLoaded’, main);。
- 渲染器尺寸与相机宽高比： 确保 renderer.setSize()被调用以设置渲染器输出画布的尺寸，并且 camera.aspect 与画布的宽高比保持一致，以避免图像拉伸。同时，添加 window.addEventListener(‘resize’, onWindowResize); 来处理窗口大小变化，使场景能够响应式调整。
- 相机位置： 确认相机已放置在场景中，并且其位置能够“看到”你添加的物体。如果相机与物体在同一位置或物体在相机后面，你将看不到任何东西。
- 场景添加物体： 确保你创建的网格（Mesh）已通过 scene.add(mesh)添加到场景中。
- 动画循环： 对于需要交互或动态变化的场景，仅仅调用一次 renderer.render()是不够的。你需要设置一个动画循环（通常使用 requestAnimationFrame），在每一帧中更新场景状态并重新渲染。
- 检查 浏览器 控制台： 尽管本问题中没有报错，但在开发过程中，始终密切关注浏览器开发者 工具 的控制台。任何javaScript 错误、资源加载失败或 WebGL 警告都可能提供关键线索。
总结
Three.js 画布不渲染而无报错的问题，通常源于对初始化函数（如 main()）的遗漏调用。通过在脚本末尾或 DOMContentLoaded 事件中显式调用该函数，可以确保所有场景设置和渲染逻辑得以执行。同时，遵循最佳实践，如处理 DOM 加载、响应式调整尺寸和合理设置相机，将有助于构建稳定且功能完善的 Three.js 应用。
