Three.js立方体纹理映射显示黑色且触发错误的原因排查

我在Three.js中尝试为立方体几何体添加纹理映射，但应用后物体变为黑色。运行以下代码时会弹出错误提示，且项目中确实存在'./wall.jpg'文件，请问出现该问题的原因是什么？

var cubeGeometry1 = new THREE.BoxGeometry(300, 30, 1);
const loader = new THREE.TextureLoader();


const cubeMaterial = new THREE.MeshBasicMaterial({
    map: loader.load("./wall.jpg", undefined, undefined, function(err) {
        alert('Error');
    }),
});
var cube1 = new THREE.Mesh(cubeGeometry1, cubeMaterial);
cube1.castShadow = true; 
cube1.position.set(0,15,-50); 
scene.add(cube1);

原因分析与解决办法 #

核心问题1：异步加载导致材质初始化无有效纹理 #

TextureLoader.load()是异步方法，调用后会立即返回一个未完成加载的空纹理对象。你直接把这个空对象赋值给MeshBasicMaterial的map属性，材质初始化时没有可用的纹理数据，就会显示黑色。同时加载失败回调触发，说明资源路径或访问权限存在异常。

核心问题2：路径解析或资源访问异常 #

• 相对路径./wall.jpg是基于当前网页的URL解析，而非脚本文件所在位置。如果HTML文件和脚本不在同一目录，或者使用了构建工具（如Vite、Webpack），路径规则会变化，导致资源找不到。
• 本地直接打开HTML文件（file://协议）时，浏览器的跨域安全策略会阻止加载本地图片，触发加载错误。

修正后的代码示例 #

var cubeGeometry1 = new THREE.BoxGeometry(300, 30, 1);
const loader = new THREE.TextureLoader();

// 等待纹理加载完成后再创建材质和网格
loader.load("./wall.jpg", function(texture) {
    const cubeMaterial = new THREE.MeshBasicMaterial({ map: texture });
    var cube1 = new THREE.Mesh(cubeGeometry1, cubeMaterial);
    cube1.castShadow = true; 
    cube1.position.set(0,15,-50); 
    scene.add(cube1);
}, undefined, function(err) {
    console.error('纹理加载失败详情:', err);
    alert('Error');
});

额外排查建议 #

• 打开浏览器开发者工具的网络面板，查看wall.jpg的请求状态：如果是404，说明路径错误；如果是跨域错误，说明需要用本地服务器运行项目。
• 构建工具环境下：把图片放在public目录，或者通过import img from './wall.jpg'导入资源，再将img作为路径传入loader.load()。
• 本地开发时，用npx serve启动简易服务器，避免file://协议的跨域限制。

内容的提问来源于stack exchange，提问作者bklee