加载 3D 模型

3D 模型有数百种文件格式，每种格式都有不同的用途、各异的特性和不同的复杂度。虽然 three.js 提供了许多加载器，但选择正确的格式和工作流可以节省大量时间，避免后续的麻烦。某些格式难以使用、不适合实时场景，或者目前尚未完全支持。

本指南提供了适用于大多数用户的推荐工作流，以及在遇到问题时的排查建议。

开始之前

如果你是第一次搭建本地服务器，请先阅读安装页面。正确托管文件可以避免许多查看 3D 模型时的常见错误。

推荐工作流

我们推荐尽可能使用 glTF（GL Transmission Format）格式。该格式的 .GLB 和 .GLTF 两种版本都得到了良好支持。由于 glTF 专注于运行时资源交付，它体积紧凑、加载速度快。支持的特性包括网格、材质、纹理、蒙皮、骨骼、变形目标、动画、灯光和相机。

公共领域的 glTF 文件可以在 Sketchfab 等网站上找到，许多工具也支持 glTF 导出：

• Blender by the Blender Foundation
• Substance Painter by Allegorithmic
• Modo by Foundry
• Toolbag by Marmoset
• Houdini by SideFX
• Cinema 4D by MAXON
• COLLADA2GLTF by the Khronos Group
• FBX2GLTF by Facebook
• OBJ2GLTF by Analytical Graphics Inc
• …以及更多工具

如果你常用的工具不支持 glTF，可以考虑向作者请求添加 glTF 导出功能，或者在 glTF 路线图讨论帖中发帖。

当 glTF 不可用时，也可以使用 FBX、OBJ 或 COLLADA 等常见格式，它们同样可用且持续维护中。

加载

three.js 默认只包含少数加载器（如 `ObjectLoader`），其他加载器需要单独添加到你的应用中。

import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

导入加载器后，就可以向场景中添加模型了。不同加载器的语法各不相同——使用其他格式时，请查阅对应加载器的示例和文档。对于 glTF，使用全局脚本的方式如下：

const loader = new GLTFLoader();

loader.load( 'path/to/model.glb', function ( gltf ) {

  scene.add( gltf.scene );

}, undefined, function ( error ) {

  console.error( error );

} );

故障排查

你花了好几个小时精心制作了一个模型，将它加载到网页中，结果——天哪！😭 它变形了、颜色不对，或者完全看不到。请按以下步骤排查：

1. 检查 JavaScript 控制台是否有错误，并确保在调用 `.load()` 时使用了 `onError` 回调来记录错误信息。
2. 在其他应用中查看模型。对于 glTF，可以使用 three.js 和 babylon.js 的拖放查看器。如果模型在一个或多个应用中显示正常，请向 three.js 提交 bug。如果模型在所有应用中都无法显示，我们强烈建议向创建该模型的应用提交 bug。
3. 尝试将模型放大或缩小 1000 倍。许多模型的缩放比例不同，如果相机位于模型内部，大型模型可能不会显示。
4. 尝试添加并调整光源位置。模型可能隐藏在黑暗中。
5. 在网络面板中查找失败的纹理请求，例如 `"C:\\Path\To\Model\texture.jpg"`。请使用相对于模型的路径，如 `images/texture.jpg`——这可能需要在文本编辑器中修改模型文件。

寻求帮助

如果你已经完成了上述排查步骤，模型仍然无法正常工作，正确的求助方式能帮你更快找到解决方案。在 three.js 论坛上发帖提问，并尽可能附上你的模型（或具有相同问题的简化模型），提供你手头的所有格式。请包含足够的信息以便他人快速复现问题——最好提供一个在线演示。