Substance Painter导出GLTF至Three.js/WebGL显示异常求助

阿华AIGC实验室

2026-5-26

解决Substance Painter导出glTF后金属材质丢失&Three.js显示异常问题

这种问题我实战中碰到过好几次，核心原因基本都是glTF导出配置和Three.js的PBR工作流不匹配，或者渲染环境/灯光设置没跟上，咱们一步步来排查解决：

一、先检查Substance Painter的导出设置（最容易踩坑的环节）

锁定Metallic-Roughness工作流：Substance Painter里导出glTF时，一定要在「Export Settings」的「Texture Set Settings」里，确认是用Metallic-Roughness模式（不是Specular-Glossiness）。Three.js对glTF的PBR支持优先适配前者，选后者大概率会导致金属材质直接变成亮黑色。
核对通道映射：确保Metallic通道绑定到glTF的metallicRoughnessTexture的R通道，Roughness绑定到G通道——这个默认是对的，但如果之前手动调整过通道，一定要改回来。
纹理格式选通用型：导出时优先用PNG或WebP，别用DDS这类压缩格式，Three.js对压缩纹理的支持需要额外配置，先拿无损格式测试排除问题。

二、调整Three.js的渲染&灯光配置

开启PBR必备的渲染参数：初始化WebGLRenderer时，必须设置这两个参数：
```
renderer.physicallyCorrectLights = true;
renderer.outputEncoding = THREE.sRGBEncoding;
```
这俩是PBR材质正确显示的核心，默认没开的话，材质会显得昏暗、颜色偏差极大。
优化灯光设置：
- DirectionalLight的默认强度（intensity）是1，对于PBR材质来说太弱了，直接调到3-5试试；
- 如果模型局部看不见，检查相机的far值是不是太小，把模型裁切掉了；
- 给场景加个HemisphereLight补环境光，金属材质需要环境反射才能体现质感，光靠平行光肯定不够。

验证材质加载是否正常：加载完成后遍历模型材质，打印关键参数确认：

model.traverse((obj) => {
  if (obj.isMesh) {
    console.log('金属度:', obj.material.metalness);
    console.log('粗糙度:', obj.material.roughness);
    console.log('金属纹理:', obj.material.metalnessMap);
  }
});

如果metalness是0或者metalnessMap为null，那肯定是导出时通道没配置对。

三、补全环境反射（还原Painter里的质感）

Substance Painter里的预览是用了HDR环境光的，而Three.js默认场景是纯黑，金属材质没有反射源就会显得死黑。你可以加载一张HDR环境贴图：

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

new RGBELoader()
  .load('你的HDR路径.hdr', function (texture) {
    texture.mapping = THREE.EquirectangularReflectionMapping;
    scene.environment = texture;
  });

这样金属材质就能反射环境光，和Painter里的预览效果就接近了。