GLTFLoader无法加载模型的常见报错如“TypeError: GLTFLoader is not a constructor”或“net::ERR_FILE_NOT_FOUND”，根本原因并非代码错误，而是环境配置不当：Three.js 0.160+已将GLTFLoader移出核心包，须单独从examples/jsm/loaders导入；且浏览器直接双击HTML（file://协议）会因CORS阻止加载本地.glb/.gltf文件，必须通过HTTP服务器（如Live Server、http-server）运行页面，并确保模型路径正确可访问。
GLTFLoader 无法加载模型的常见报错
看到 TypeError: GLTFLoader is not a constructor 或 Failed to load resource: net::ERR_FILE_NOT_FOUND？说明不是代码写错了，而是环境或路径没配对。Three.js 自 0.160 版起已将 GLTFLoader 移出核心包，必须单独导入；同时浏览器直接双击打开 HTML 文件（file:// 协议）会因 CORS 拒绝加载本地 .glb 或 .gltf 文件——这是最常卡住的地方。
- 必须用 HTTP 服务运行页面（如 VS Code 的 Live Server 插件、
npx http-server），不能直接双击 HTML -
GLTFLoader需从three/examples/jsm/loaders/GLTFLoader.js导入，不是three主包里 - 确保模型文件放在能被服务器访问到的路径下，比如和 HTML 同级的
models/scene.glb
ES Module 方式正确导入与初始化
用现代 ES Module 加载时，import 语句顺序和路径必须精确。Three.js 的模块化结构很严格，漏掉 OrbitControls 或 RGBELoader 不影响 GLTFLoader 本身，但漏掉 THREE 核心或 GLTFLoader 路径就直接报错。
最小可用代码片段：
import * as THREE from 'https://cdn.jsdelivr.net/npm/three@0.160.1/+esm';
import { GLTFLoader } from 'https://cdn.jsdelivr.net/npm/three@0.160.1/examples/jsm/loaders/GLTFLoader.js';
import { OrbitControls } from 'https://cdn.jsdelivr.net/npm/three@0.160.1/examples/jsm/controls/OrbitControls.js';
<p>const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);</p><p>const loader = new GLTFLoader();
loader.load(
'models/robot.glb',
(gltf) => {
scene.add(gltf.scene);
},
undefined,
(error) => console.error('加载失败:', error)
);</p>模型缩放、位置与材质适配要点
加载进来的模型经常小得看不见，或黑乎乎没光照，不是代码问题，而是 glTF 模型自带单位、坐标系和 PBR 材质依赖环境光。默认 scene 是纯黑无光的，gltf.scene 也未必按你预期朝向。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
- 加一个
THREE.AmbientLight(0xffffff, 0.5)和至少一个THREE.DirectionalLight，否则 PBR 材质不显示颜色 - 用
gltf.scene.scale.set(5, 5, 5)快速放大；用gltf.scene.position.set(0, -1, 0)把它“抬”到地面附近 - 如果模型是 Y-up（Blender 默认），而你的场景是 Z-up（Three.js 默认），可能需要
gltf.scene.rotation.x = -Math.PI / 2 - 想改材质？别直接赋新
material，先等gltf.scene.traverse遍历到Mesh再改，否则会被 glTF 内置材质覆盖
本地开发时绕过 CORS 的临时方案
不想每次开服务器？Chrome 可以临时禁用安全策略（仅开发用）：
关闭所有 Chrome 窗口 → 终端执行：chrome --disable-web-security --user-data-dir=/tmp/chrome-dev。但注意：这不会解决 GLTFLoader is not a constructor 类错误，只解决 net::ERR_FAILED 类加载失败。
真正稳定的做法，还是把模型放服务器路径下，并确认控制台 Network 标签页里 models/xxx.glb 返回状态码是 200。路径错一个字母、少个斜杠、大小写不一致，在 macOS/Linux 上都可能加载失败。
