在Three.js中使用GLTFLoader加载模型时，不少项目都会遇到模型显示正常但表面完全没有纹理的情况。这个问题通常不是Three.js本身的缺陷，而是资源解析、文件结构或加载配置中的某个环节出现了断裂。要彻底解决，需要先理解glTF资源的组织方式以及Loader的工作机制，再针对具体环节逐一排查。
一、理解glTF的纹理引用机制
glTF是一种基于JSON的开放三维资源格式，它的几何数据、材质参数和纹理图片可以是分开的文件，也可以内嵌在同一个二进制包（.glb）中。在.gltf文本文件里，纹理通常通过images字段指向外部图片路径，例如相对目录下的diffuse.png，或者通过bufferViews引用内嵌的二进制数据。GLTFLoader在解析时，会根据basePath拼接这些相对路径去发起网络请求。
如果纹理图片没有被正确加载，模型依然会渲染，只是材质会回退到默认颜色或白色，看起来就是“无纹理”。这和传统OBJ+MTL加载失败直接报错不同，glTF设计上更倾向于静默降级，因此排查时不能只依赖控制台报错，还要主动检查加载回调里的材质状态。
1.1 外部资源与内嵌资源的差异
使用.blend等工具导出的glTF如果选择分离式导出，会生成.gltf、.bin以及若干图片。此时图片路径如果写成了绝对路径，或者服务器子目录变动，Loader就会404。而.glb单文件格式把图片转成buffer，不容易出现路径问题，但体积更大。理解这一点有助于判断该优先检查网络请求还是检查文件解析。
下面是一段典型的分离式glTF片段结构，注意images里的uri是相对引用：
{
"images": [
{
"uri": "texture_0.png"
}
],
"textures": [
{
"source": 0
}
],
"materials": [
{
"pbrMetallicRoughness": {
"baseColorTexture": {
"index": 0
}
}
}
]
}
二、常见无纹理原因与排查清单
导致GLTFLoader加载后无纹理的原因集中在路径、服务器、扩展和代码配置四个方面。我们逐一展开说明，并给出对应的检查手段。
2.1 资源路径与basePath配置错误
GLTFLoader默认以加载的.gltf文件所在URL作为basePath。如果你通过fetch拿到了JSON字符串再用parse方法手动解析，就需要显式传入资源根目录，否则图片请求会指向当前页面域名根目录。正确做法是在调用loader.load时传入完整URL，或使用setPath设置基础路径。
以下代码展示了错误与正确用法对比：
// 错误：手动parse但未指定路径，纹理请求会发到页面根目录
const json = await fetch('models/box.gltf').then(r => r.json());
loader.parse(JSON.stringify(json), '', gltf => scene.add(gltf.scene));
// 正确：指定资源基础路径
loader.load('models/box.gltf', gltf => {
scene.add(gltf.scene);
}, undefined, undefined);
// 或者手动parse时给第二个参数传basePath
loader.parse(JSON.stringify(json), 'models/', gltf => scene.add(gltf.scene));
2.2 服务器MIME类型与跨域限制
部分静态服务器对.gltf、.bin或.png返回的Content-Type不正确，虽不影响图片显示，但可能让Loader在解析前就拒绝。更常见的是跨域：如果模型放在CDN，而CDN未配置Access-Control-Allow-Origin，图片请求会被浏览器拦截，纹理自然丢失。开发阶段可先用同源本地服务验证，再处理跨域头。
可在浏览器Network面板筛选图片请求，看状态码与响应头。若显示CORS错误，需在服务端添加允许跨域，例如Nginx配置：
location /models/ {
add_header Access-Control-Allow-Origin *;
types {
model/gltf+json gltf;
model/gltf-binary glb;
}
}
2.3 扩展材质未被支持
有些美术在导出时使用了KHR_materials_unlit或KHR_materials_clearcoat等扩展。如果Three.js版本较老，未包含对应扩展解析器，相关纹理通道会被忽略。应确保three包版本不低于r132，并在导入时确认GLTFLoader已自动注册扩展，无需手动写插件。
可通过打印材质对象检查是否有map属性为空：
gltf.scene.traverse(child => {
if (child.isMesh) {
console.log(child.material.name, child.material.map);
}
});
三、构建工具下的稳定加载实践
在Webpack或Vite项目中，直接把模型放进src目录可能被打包器改写路径。推荐将模型与纹理放在public目录，以绝对路径加载，避免哈希重命名破坏引用。
3.1 Vite项目中的目录约定
Vite的public文件夹内容会原样拷贝到 dist 根目录。将models/box.gltf及同目录图片置于public/models下，代码中用 '/models/box.gltf' 加载，basePath自动指向正确位置，不会因模块打包而丢失纹理。
示例加载代码：
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
const loader = new GLTFLoader();
loader.load('/models/box.gltf', gltf => {
scene.add(gltf.scene);
}, xhr => {
console.log((xhr.loaded / xhr.total) * 100 + '% loaded');
}, err => {
console.error('加载失败', err);
});
3.2 使用DRACO与KTX2时的注意事项
若模型用了DRACO压缩几何、KTX2压缩纹理，需要配置对应解码器路径，否则整个模型或纹理无法解析。GLTFLoader提供setDRACOLoader与setKTX2Loader方法，解码器文件也应放public目录并通过setDecoderPath指向。
配置示例：
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
const draco = new DRACOLoader();
draco.setDecoderPath('/draco/');
loader.setDRACOLoader(draco);
四、总结与最佳实践
排查GLTFLoader无纹理问题，核心思路是确认纹理请求是否成功、材质map是否赋值、扩展是否被解析。日常最佳实践是优先使用.glb减少路径问题，将资源置于public静态目录，加载后在遍历模型中打印材质状态做断言。
当团队协同美术与开发时，应约定导出规范：分离资源也保持相对目录结构，避免中文路径，统一使用sRGB色彩空间的贴图。这样能在Three.js中最大限度减少“模型加载成功却无纹理”的返工情况，让渲染结果符合预期。
GLTFLoader模型纹理Three.js修改时间：2026-08-03 16:42:37